NAME

imgif.c - read and write gif files for Imager

SYNOPSIS

i_img *img;
i_img *imgs[count];
int fd;
int *colour_table,
int colours;
int max_colours; // number of bits per colour
int pixdev;  // how much noise to add 
i_color fixed[N]; // fixed palette entries 
int fixedlen; // number of fixed colours 
int success; // non-zero on success
char *data; // a GIF file in memory
int length; // how big data is 
int reader(char *, char *, int, int);
int writer(char *, char *, int);
char *userdata; // user's data, whatever it is
i_quantize quant;
i_gif_opts opts;

img = i_readgif(fd, &colour_table, &colours);
success = i_writegif(img, fd, max_colours, pixdev, fixedlen, fixed);
success = i_writegifmc(img, fd, max_colours);
img = i_readgif_scalar(data, length, &colour_table, &colours);
img = i_readgif_callback(cb, userdata, &colour_table, &colours);
success = i_writegif_gen(&quant, fd, imgs, count, &opts);
success = i_writegif_callback(&quant, writer, userdata, maxlength, 
                              imgs, count, &opts);

DESCRIPTION

This source file provides the C level interface to reading and writing GIF files for Imager.

This has been tested with giflib 3 and 4, though you lose the callback functionality with giflib3.

REFERENCE

i_readgif_low(GifFileType *GifFile, int **colour_table, int *colours)

Internal. Low-level function for reading a GIF file. The caller must create the appropriate GifFileType object and pass it in.

i_readgif_multi_low(GifFileType *gf, int *count, int page)

Reads one of more gif images from the given GIF file.

Returns a pointer to an array of i_img *, and puts the count into *count.

If page is not -1 then the given image _only_ is returned from the file, where the first image is 0, the second 1 and so on.

Unlike the normal i_readgif*() functions the images are paletted images rather than a combined RGB image.

This functions sets tags on the images returned:

gif_left

the offset of the image from the left of the "screen" ("Image Left Position")

gif_top

the offset of the image from the top of the "screen" ("Image Top Position")

gif_interlace

non-zero if the image was interlaced ("Interlace Flag")

gif_screen_width

gif_screen_height

the size of the logical screen ("Logical Screen Width", "Logical Screen Height")

gif_local_map

Non-zero if this image had a local color map.

gif_background

The index in the global colormap of the logical screen's background color. This is only set if the current image uses the global colormap.

gif_trans_index

The index of the color in the colormap used for transparency. If the image has a transparency then it is returned as a 4 channel image with the alpha set to zero in this palette entry. ("Transparent Color Index")

gif_delay

The delay until the next frame is displayed, in 1/100 of a second. ("Delay Time").

gif_user_input

whether or not a user input is expected before continuing (view dependent) ("User Input Flag").

gif_disposal

how the next frame is displayed ("Disposal Method")

gif_loop

the number of loops from the Netscape Loop extension. This may be zero.

gif_comment

the first block of the first gif comment before each image.

Where applicable, the ("name") is the name of that field from the GIF89 standard.

i_readgif_multi_wiol(ig, int *count)

i_readgif_single_low(GifFile, page)

Lower level function to read a single image from a GIF.

page must be non-negative.

i_readgif_single_wiol(ig, page)

Read a single page from a GIF image file, where the page is indexed from 0.

Returns NULL if the page isn't found.

do_write(GifFileType *gf, i_gif_opts *opts, i_img *img, i_palidx *data)

Internal. Low level image write function. Writes in interlace if that was requested in the GIF options.

Returns non-zero on success.

do_gce(GifFileType *gf, int index, i_gif_opts *opts, int want_trans, int trans_index)

Internal. Writes the GIF graphics control extension, if necessary.

Returns non-zero on success.

do_comments(gf, img)

Write any comments in the image.

do_ns_loop(GifFileType *gf, i_gif_opts *opts)

Internal. Add the Netscape2.0 loop extension block, if requested.

Giflib/libungif prior to 4.1.1 didn't support writing application extension blocks, so we don't attempt to write them for older versions.

Giflib/libungif prior to 4.1.3 used the wrong write mechanism when writing extension blocks so that they could only be written to files.

make_gif_map(i_quantize *quant, int want_trans)

Create a giflib color map object from an Imager color map.

need_version_89a(i_quantize *quant, i_img *imgs, int count)

Return true if the file we're creating on these images needs a GIF89a header.

has_common_palette(imgs, count, quant)

Tests if all the given images are paletted and their colors are in the palette produced.

Previously this would build a consolidated palette from the source, but that meant that if the caller supplied a static palette (or specified a fixed palette like "webmap") then we wouldn't be quantizing to the caller specified palette.

i_writegif_low(i_quantize *quant, GifFileType *gf, i_img **imgs, int count, i_gif_opts *opts)

Internal. Low-level function that does the high-level GIF processing :)

Returns non-zero on success.

i_writegif_wiol(ig, quant, opts, imgs, count)

gif_error_msg(int code)

Grabs the most recent giflib error code from GifLastError() and returns a string that describes that error.

Returns NULL for unknown error codes.

gif_push_error(code)

Utility function that takes the current GIF error code, converts it to an error message and pushes it on the error stack.

AUTHOR

Arnar M. Hrafnkelsson, addi@umich.edu

Tony Cook <tonyc@cpan.org>

SEE ALSO

perl(1), Imager(3)