Write GIF images.
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. |
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.
im | The image to write |
size | Output: the size of the resulting image. |
A pointer to the GIF data or NULL if an error occurred.
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.
gdImageGifCtx outputs the image via a gdIOCtx struct.
gdImageGifPtr stores the image in a large array of bytes.
im | The image to write |
outFile | The FILE pointer to write the image to. |
Nothing
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);
void gdImageGifCtx( gdImagePtr im, gdIOCtxPtr out )
Writes a GIF image via a gdIOCtx. See gdImageGif.
im | The image to write |
out | The gdIOCtx struct used to do the writing. |
Nothing.
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.
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 |
A pointer to the resulting data (the contents of the start of the GIF) or NULL if an error occurred.
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.
gdImageGifAnimBeginCtx outputs the image via a gdIOCtx struct.
gdImageGifAnimBeginPtr stores the image in a large array of bytes.
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 |
Nothing.
See gdImageGifAnimBegin.
void gdImageGifAnimBeginCtx( gdImagePtr im, gdIOCtxPtr out, int GlobalCM, int Loops )
Like gdImageGifAnimBegin except that it outputs to gdIOCtx. See gdImageGifAnimBegin.
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 |
Nothing.
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.
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. |
Pointer to the resulting data or NULL if an error occurred.
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.
gdImageGifAnimAddCtx outputs its data via a gdIOCtx struct.
gdImageGifAnimAddPtr outputs its data to a memory buffer which it returns.
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. |
Nothing.
{ 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); }
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>.
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. |
Nothing.
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.)
gdImageGifAnimEndCtx outputs its data via a gdIOCtx struct.
gdImageGifAnimEndPtr outputs its data to a memory buffer which it returns.
outfile | the destination FILE*. |
Nothing.
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.
size | Output: the size of the resulting buffer. |
Pointer to the resulting data or NULL if an error occurred.
void gdImageGifAnimEndCtx( gdIOCtx * out )
Like gdImageGifAnimEnd, but writes its data via a gdIOCtx.
out | the destination gdIOCtx. |
Nothing.
Identical to gdImageGif except that it returns a pointer to a memory area with the GIF data.
void * gdImageGifPtr( gdImagePtr im, int * size )
gdImageGif outputs the specified image to the specified file in GIF format.
void gdImageGif( gdImagePtr im, FILE * outFile )
Writes a GIF image via a gdIOCtx.
void gdImageGifCtx( gdImagePtr im, gdIOCtxPtr out )
Like gdImageGifAnimBegin except that it outputs to a memory buffer.
void * gdImageGifAnimBeginPtr( gdImagePtr im, int * size, int GlobalCM, int Loops )
This function must be called as the first function when creating a GIF animation.
void gdImageGifAnimBegin( gdImagePtr im, FILE * outFile, int GlobalCM, int Loops )
Like gdImageGifAnimBegin except that it outputs to gdIOCtx.
void gdImageGifAnimBeginCtx( gdImagePtr im, gdIOCtxPtr out, int GlobalCM, int Loops )
Like gdImageGifAnimAdd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
void * gdImageGifAnimAddPtr( gdImagePtr im, int * size, 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 gdImageGifAnimAdd( gdImagePtr im, FILE * outFile, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm )
Adds an animation frame via a gdIOCtxPtr.
void gdImageGifAnimAddCtx( gdImagePtr im, gdIOCtxPtr out, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm )
Terminates the GIF file properly.
void gdImageGifAnimEnd( FILE * outFile )
Like gdImageGifAnimEnd (which contains more information) except that it stores the data to write into memory and returns a pointer to it.
void * gdImageGifAnimEndPtr( int * size )
Like gdImageGifAnimEnd, but writes its data via a gdIOCtx.
void gdImageGifAnimEndCtx( gdIOCtx * out )
Frees memory that has been allocated by libgd functions.
void gdFree ( void * ptr )
Creates a new palette image from a truecolor image
gdImagePtr gdImageCreatePaletteFromTrueColor ( gdImagePtr im, int dither, int colorsWanted )
void gdImagePaletteCopy ( gdImagePtr to, gdImagePtr from )