GIF Output

Write GIF images.

Summary
GIF OutputWrite GIF images.
Functions
gdImageGifPtrIdentical to gdImageGif except that it returns a pointer to a memory area with the GIF data.
gdImageGifgdImageGif outputs the specified image to the specified file in GIF format.
gdImageGifCtxWrites a GIF image via a gdIOCtx.
gdImageGifAnimBeginPtrLike gdImageGifAnimBegin except that it outputs to a memory buffer.
gdImageGifAnimBeginThis function must be called as the first function when creating a GIF animation.
gdImageGifAnimBeginCtxLike gdImageGifAnimBegin except that it outputs to gdIOCtx.
gdImageGifAnimAddPtrLike gdImageGifAnimAdd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
gdImageGifAnimAddThis function writes GIF animation frames to GIF animation, which was initialized with gdImageGifAnimBegin.
gdImageGifAnimAddCtxAdds an animation frame via a <gdIOCtxPtr>.
gdImageGifAnimEndTerminates the GIF file properly.
gdImageGifAnimEndPtrLike gdImageGifAnimEnd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
gdImageGifAnimEndCtxLike gdImageGifAnimEnd, but writes its data via a gdIOCtx.

Functions

gdImageGifPtr

void * gdImageGifPtr(gdImagePtr im,
int *size)

Identical to gdImageGif except that it returns a pointer to a memory area with the GIF data.  This memory must be freed by the caller when it is no longer needed.

The caller must invoke gdFree, not free().  This is because it is not guaranteed that libgd will use the same implementation of malloc, free, etc. as your proggram.

The ‘size’ parameter receives the total size of the block of memory.

Parameters

imThe image to write
sizeOutput: the size of the resulting image.

Returns

A pointer to the GIF data or NULL if an error occurred.

gdImageGif

void gdImageGif(gdImagePtr im,
FILE *outFile)

gdImageGif outputs the specified image to the specified file in GIF format.  The file must be open for binary writing.  (Under MSDOS and all versions of Windows, it is important to use “wb” as opposed to simply “w” as the mode when opening the file; under Unix there is no penalty for doing so).  gdImageGif does not close the file; your code must do so.

GIF does not support true color; GIF images can contain a maximum of 256 colors.  If the image to be written is a truecolor image, such as those created with gdImageCreateTrueColor or loaded from a JPEG or a truecolor PNG image file, a palette-based temporary image will automatically be created internally using the gdImageCreatePaletteFromTrueColor function.  The original image pixels are not modified.  This conversion produces high quality palettes but does require some CPU time.  If you are regularly converting truecolor to palette in this way, you should consider creating your image as a palette-based image in the first place.

Variants

gdImageGifCtx outputs the image via a gdIOCtx struct.

gdImageGifPtr stores the image in a large array of bytes.

Parameters

imThe image to write
outFileThe FILE pointer to write the image to.

Returns

Nothing

Example

gdImagePtr im;
int black, white;
FILE *out;
// Create the image
im = gdImageCreate(100, 100);
// Allocate background
white = gdImageColorAllocate(im, 255, 255, 255);
// Allocate drawing color
black = gdImageColorAllocate(im, 0, 0, 0);
// Draw rectangle
gdImageRectangle(im, 0, 0, 99, 99, black);
// Open output file in binary mode
out = fopen("rect.gif", "wb");
// Write GIF
gdImageGif(im, out);
// Close file
fclose(out);
// Destroy image
gdImageDestroy(im);

gdImageGifCtx

void gdImageGifCtx(gdImagePtr im,
gdIOCtxPtr out)

Writes a GIF image via a gdIOCtx.  See gdImageGif.

Parameters

imThe image to write
outThe gdIOCtx struct used to do the writing.

Returns

Nothing.

gdImageGifAnimBeginPtr

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

Like gdImageGifAnimBegin except that it outputs to a memory buffer.  See gdImageGifAnimBegin.

The returned memory must be freed by the caller when it is no longer needed.  **The caller must invoke <gdFree>(), not free()**, unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time (but don’t; it could always change).

The ‘size’ parameter receives the total size of the block of memory.

Parameters

imThe reference image
sizeOutput: the size in bytes of the result.
GlobalCMGlobal colormap flag: 1 -> yes, 0 -> no, -1 -> do default
LoopsLoop count; 0 -> infinite, -1 means no loop

Returns

A pointer to the resulting data (the contents of the start of the GIF) or NULL if an error occurred.

gdImageGifAnimBegin

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

This function must be called as the first function when creating a GIF animation.  It writes the correct GIF file headers to selected file output, and prepares for frames to be added for the animation.  The image argument is not used to produce an image frame to the file, it is only used to establish the GIF animation frame size, interlacing options and the color palette.  gdImageGifAnimAdd is used to add the first and subsequent frames to the animation, and the animation must be terminated by writing a semicolon character (;) to it or by using gdImageGifAnimEnd to do that.

The GlobalCM flag indicates if a global color map (or palette) is used in the GIF89A header.  A nonzero value specifies that a global color map should be used to reduce the size of the animation.  Of course, if the color maps of individual frames differ greatly, a global color map may not be a good idea.  GlobalCM=1 means write global color map, GlobalCM=0 means do not, and GlobalCM=-1 means to do the default, which currently is to use a global color map.

If Loops is 0 or greater, the Netscape 2.0 extension for animation loop count is written.  0 means infinite loop count.  -1 means that the extension is not added which results in no looping.  -1 is the default.

Variants

gdImageGifAnimBeginCtx outputs the image via a gdIOCtx struct.

gdImageGifAnimBeginPtr stores the image in a large array of bytes.

Parameters

imThe reference image
outfileThe output FILE*.
GlobalCMGlobal colormap flag: 1 -> yes, 0 -> no, -1 -> do default
LoopsLoop count; 0 -> infinite, -1 means no loop

Returns

Nothing.

Example

See gdImageGifAnimBegin.

gdImageGifAnimBeginCtx

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

Like gdImageGifAnimBegin except that it outputs to gdIOCtx.  See gdImageGifAnimBegin.

Parameters

imThe reference image
outPointer to the output gdIOCtx.
GlobalCMGlobal colormap flag: 1 -> yes, 0 -> no, -1 -> do default
LoopsLoop count; 0 -> infinite, -1 means no loop

Returns

Nothing.

gdImageGifAnimAddPtr

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

Like gdImageGifAnimAdd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.

This memory must be freed by the caller when it is no longer needed.  **The caller must invoke <gdFree>(), not free(),** unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time (but don’t; it could always change).

The ‘size’ parameter receives the total size of the block of memory.

Parameters

imThe image to add.
sizeOutput: the size of the resulting buffer.
LocalCMFlag.  If 1, use a local color map for this frame.
LeftOfsLeft offset of image in frame.
TopOfsTop offset of image in frame.
DelayDelay before next frame (in 1/100 seconds)
DisposalMODE: How to treat this frame when the next one loads.
previmNULL or a pointer to the previous image written.

Returns

Pointer to the resulting data or NULL if an error occurred.

gdImageGifAnimAdd

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

This function writes GIF animation frames to GIF animation, which was initialized with gdImageGifAnimBegin.  With LeftOfs and TopOfs you can place this frame in different offset than (0,0) inside the image screen as defined in gdImageGifAnimBegin.  Delay between the previous frame and this frame is in 1/100s units.  Disposal is usually gdDisposalNone, meaning that the pixels changed by this frame should remain on the display when the next frame begins to render, but can also be gdDisposalUnknown (not recommended), gdDisposalRestoreBackground (restores the first allocated color of the global palette), or gdDisposalRestorePrevious (restores the appearance of the affected area before the frame was rendered).  Only gdDisposalNone is a sensible choice for the first frame.  If previm is passed, the built-in GIF optimizer will always use gdDisposalNone regardless of the Disposal parameter.

Setting the LocalCM flag to 1 adds a local palette for this image to the animation.  Otherwise the global palette is assumed and the user must make sure the palettes match.  Use gdImagePaletteCopy to do that.

Automatic optimization is activated by giving the previous image as a parameter.  This function then compares the images and only writes the changed pixels to the new frame in animation.  The Disposal parameter for optimized animations must be set to 1, also for the first frame.  LeftOfs and TopOfs parameters are ignored for optimized frames.  To achieve good optimization, it is usually best to use a single global color map.  To allow gdImageGifAnimAdd to compress unchanged pixels via the use of a transparent color, the image must include a transparent color.

Variants

gdImageGifAnimAddCtx outputs its data via a gdIOCtx struct.

gdImageGifAnimAddPtr outputs its data to a memory buffer which it returns.

Parameters

imThe image to add.
outfileThe output FILE* being written.
LocalCMFlag.  If 1, use a local color map for this frame.
LeftOfsLeft offset of image in frame.
TopOfsTop offset of image in frame.
DelayDelay before next frame (in 1/100 seconds)
DisposalMODE: How to treat this frame when the next one loads.
previmNULL or a pointer to the previous image written.

Returns

Nothing.

Example

{
gdImagePtr im, im2, im3;
int black, white, trans;
FILE *out;

im = gdImageCreate(100, 100);     // Create the image
white = gdImageColorAllocate(im, 255, 255, 255); // Allocate background
black = gdImageColorAllocate(im, 0, 0, 0); // Allocate drawing color
trans = gdImageColorAllocate(im, 1, 1, 1); // trans clr for compression
gdImageRectangle(im, 0, 0, 10, 10, black); // Draw rectangle

out = fopen("anim.gif", "wb");// Open output file in binary mode
gdImageGifAnimBegin(im, out, 1, 3);// Write GIF hdr, global clr map,loops
// Write the first frame.  No local color map.  Delay = 1s
gdImageGifAnimAdd(im, out, 0, 0, 0, 100, 1, NULL);

// construct the second frame
im2 = gdImageCreate(100, 100);
(void)gdImageColorAllocate(im2, 255, 255, 255); // White background
gdImagePaletteCopy (im2, im);  // Make sure the palette is identical
gdImageRectangle(im2, 0, 0, 15, 15, black);    // Draw something
// Allow animation compression with transparent pixels
gdImageColorTransparent (im2, trans);
gdImageGifAnimAdd(im2, out, 0, 0, 0, 100, 1, im);  // Add second frame

// construct the third frame
im3 = gdImageCreate(100, 100);
(void)gdImageColorAllocate(im3, 255, 255, 255); // white background
gdImagePaletteCopy (im3, im); // Make sure the palette is identical
gdImageRectangle(im3, 0, 0, 15, 20, black); // Draw something
// Allow animation compression with transparent pixels
gdImageColorTransparent (im3, trans);
// Add the third frame, compressing against the second one
gdImageGifAnimAdd(im3, out, 0, 0, 0, 100, 1, im2);
gdImageGifAnimEnd(out);  // End marker, same as putc(';', out);
fclose(out); // Close file

// Destroy images
gdImageDestroy(im);
gdImageDestroy(im2);
gdImageDestroy(im3);
}

gdImageGifAnimAddCtx

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

Adds an animation frame via a <gdIOCtxPtr>.  See gdImageGifAnimAdd>.

Parameters

imThe image to add.
outThe output <gdIOCtxPtr>.
LocalCMFlag.  If 1, use a local color map for this frame.
LeftOfsLeft offset of image in frame.
TopOfsTop offset of image in frame.
DelayDelay before next frame (in 1/100 seconds)
DisposalMODE: How to treat this frame when the next one loads.
previmNULL or a pointer to the previous image written.

Returns

Nothing.

gdImageGifAnimEnd

void gdImageGifAnimEnd(FILE *outFile)

Terminates the GIF file properly.

(Previous versions of this function’s documentation suggested just manually writing a semicolon (‘;’) instead since that is all this function does.  While that has no longer changed, we now suggest that you do not do this and instead always call gdImageGifAnimEnd (or equivalent) since later versions could possibly do more or different things.)

Variants

gdImageGifAnimEndCtx outputs its data via a gdIOCtx struct.

gdImageGifAnimEndPtr outputs its data to a memory buffer which it returns.

Parameters

outfilethe destination FILE*.

Returns

Nothing.

gdImageGifAnimEndPtr

void * gdImageGifAnimEndPtr(int *size)

Like gdImageGifAnimEnd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.

This memory must be freed by the caller when it is no longer needed.  **The caller must invoke <gdFree>(), not free(),** unless the caller is absolutely certain that the same implementations of malloc, free, etc. are used both at library build time and at application build time (but don’t; it could always change).

The ‘size’ parameter receives the total size of the block of memory.

Parameters

sizeOutput: the size of the resulting buffer.

Returns

Pointer to the resulting data or NULL if an error occurred.

gdImageGifAnimEndCtx

void gdImageGifAnimEndCtx(gdIOCtx *out)

Like gdImageGifAnimEnd, but writes its data via a gdIOCtx.

Parameters

outthe destination gdIOCtx.

Returns

Nothing.

void * gdImageGifPtr(gdImagePtr im,
int *size)
Identical to gdImageGif except that it returns a pointer to a memory area with the GIF data.
void gdImageGif(gdImagePtr im,
FILE *outFile)
gdImageGif outputs the specified image to the specified file in GIF format.
void gdImageGifCtx(gdImagePtr im,
gdIOCtxPtr out)
Writes a GIF image via a gdIOCtx.
gdIOCtx structures hold function pointers for doing image IO.
void * gdImageGifAnimBeginPtr(gdImagePtr im,
int *size,
int GlobalCM,
int Loops)
Like gdImageGifAnimBegin except that it outputs to a memory buffer.
void gdImageGifAnimBegin(gdImagePtr im,
FILE *outFile,
int GlobalCM,
int Loops)
This function must be called as the first function when creating a GIF animation.
void gdImageGifAnimBeginCtx(gdImagePtr im,
gdIOCtxPtr out,
int GlobalCM,
int Loops)
Like gdImageGifAnimBegin except that it outputs to gdIOCtx.
void * gdImageGifAnimAddPtr(gdImagePtr im,
int *size,
int LocalCM,
int LeftOfs,
int TopOfs,
int Delay,
int Disposal,
gdImagePtr previm)
Like gdImageGifAnimAdd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
void gdImageGifAnimAdd(gdImagePtr im,
FILE *outFile,
int LocalCM,
int LeftOfs,
int TopOfs,
int Delay,
int Disposal,
gdImagePtr previm)
This function writes GIF animation frames to GIF animation, which was initialized with gdImageGifAnimBegin.
void gdImageGifAnimAddCtx(gdImagePtr im,
gdIOCtxPtr out,
int LocalCM,
int LeftOfs,
int TopOfs,
int Delay,
int Disposal,
gdImagePtr previm)
Adds an animation frame via a gdIOCtxPtr.
void gdImageGifAnimEnd(FILE *outFile)
Terminates the GIF file properly.
void * gdImageGifAnimEndPtr(int *size)
Like gdImageGifAnimEnd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
void gdImageGifAnimEndCtx(gdIOCtx *out)
Like gdImageGifAnimEnd, but writes its data via a gdIOCtx.
void gdFree (void *ptr)
Frees memory that has been allocated by libgd functions.
gdImagePtr gdImageCreatePaletteFromTrueColor (gdImagePtr im,
int dither,
int colorsWanted)
Creates a new palette image from a truecolor image
Preserve previous frame
Not recommended
First allocated color of palette
Restore to before start of frame
void gdImagePaletteCopy (gdImagePtr to,
gdImagePtr from)
Close