# GIF Output

Write GIF images.

Summary

GIF Output | Write GIF images.
Functions |
gdImageGifPtr | Identical to gdImageGif except that it returns a pointer to a memory area with the GIF data.
gdImageGif | gdImageGif outputs the specified image to the specified file in GIF format.
gdImageGifCtx | Writes a GIF image via a gdIOCtx.
gdImageGifAnimBeginPtr | Like gdImageGifAnimBegin except that it outputs to a memory buffer.
gdImageGifAnimBegin | This function must be called as the first function when creating a GIF animation.
gdImageGifAnimBeginCtx | Like gdImageGifAnimBegin except that it outputs to gdIOCtx.
gdImageGifAnimAddPtr | Like gdImageGifAnimAdd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
gdImageGifAnimAdd | This function writes GIF animation frames to GIF animation, which was initialized with gdImageGifAnimBegin.
gdImageGifAnimAddCtx | Adds an animation frame via a <gdIOCtxPtr>.
gdImageGifAnimEnd | Terminates the GIF file properly.
gdImageGifAnimEndPtr | Like gdImageGifAnimEnd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
gdImageGifAnimEndCtx | Like 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

im | The image to write
size | Output: 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

im | The image to write
outFile | The 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

im | The image to write
out | The 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

im | The reference image
size | Output: the size in bytes of the result.
GlobalCM | Global colormap flag: 1 -> yes, 0 -> no, -1 -> do default
Loops | Loop 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

im | The reference image
outfile | The output FILE*.
GlobalCM | Global colormap flag: 1 -> yes, 0 -> no, -1 -> do default
Loops | Loop 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

im | The reference image
out | Pointer to the output gdIOCtx.
GlobalCM | Global colormap flag: 1 -> yes, 0 -> no, -1 -> do default
Loops | Loop 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

im | The image to add.
size | Output: the size of the resulting buffer.
LocalCM | Flag. If 1, use a local color map for this frame.
LeftOfs | Left offset of image in frame.
TopOfs | Top offset of image in frame.
Delay | Delay before next frame (in 1/100 seconds)
Disposal | MODE: How to treat this frame when the next one loads.
previm | NULL 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

im | The image to add.
outfile | The output FILE* being written.
LocalCM | Flag. If 1, use a local color map for this frame.
LeftOfs | Left offset of image in frame.
TopOfs | Top offset of image in frame.
Delay | Delay before next frame (in 1/100 seconds)
Disposal | MODE: How to treat this frame when the next one loads.
previm | NULL 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

im | The image to add.
out | The output <gdIOCtxPtr>.
LocalCM | Flag. If 1, use a local color map for this frame.
LeftOfs | Left offset of image in frame.
TopOfs | Top offset of image in frame.
Delay | Delay before next frame (in 1/100 seconds)
Disposal | MODE: How to treat this frame when the next one loads.
previm | NULL 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

outfile | the 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

size | Output: 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

out | the 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