#ifndef _GIF_H_ac765a0c_ #define _GIF_H_ac765a0c_ typedef struct gifreader GIFREADER; typedef struct gifreader_ops GIFREADER_OPS; /* * Ops take a cookie argument, which is the second arg to * gifreader_open. For brevity, in the arglist descriptions below, * this is called `cookie' and is not further described. */ struct gifreader_ops { /* * Read input. (*read_input)(cookie,buf,len): buf is the buffer to * store the data into and len is the number of bytes to read. * Return value is <0 if a read error occurred, equal to len if all * went well, or some other value (in [0..len) or >len) for * premature EOF. */ int (*read_input)(void *, void *, int); /* * An error occurred. (*error)(cookie,err,...): err is the error * number, one of the GIFREAD_ERR_* constants from below, and the * presence, number, and semantics of the following args, if any, * depend on which value err has - they are documented with the * GIFREAD_ERR_* values, below. */ void (*error)(void *, int, ...); /* * Pass back detailed information on the file. * (*detail)(cookie,what,...): what is one of the GIFREAD_DETAIL_* * values from below, and the presence, number, and semantics of the * following args, if any, depend on which value what has - they are * documented with the GIFREAD_DETAIL_* values, below. (*detail)() * calls are made for only those bits that were set in the third arg * to gifreader_open(); other details are not passed back. The * library never calls this with more than one bit set in the second * argument. */ void (*detail)(void *, unsigned int, ...); } ; #define GIFREADER_OPS_INIT(prefix) {\ &prefix##_read_input, \ &prefix##_error, \ &prefix##_detail, \ } /* * Second arg to (*error)(), and varargs args. Also indicated is what * the recovery from the error is. If an error is `fatal', there is * no recovery; the GIFREADER becomes useless after this error occurs * and the only useful thing to do is to tear it down. Except as * stated, data pointed to by argument pointers is not promised to * remain valid after (*error)() returns. */ /* * Error from (*read_input)(). Fatal. Args: one const char *, saying * what the library was trying to read when it got the error. */ #define GIFREAD_ERR_READERROR 1 /* * Unexpected EOF from (*read_input)(). Fatal. Args: one const char * *, saying what the library was trying to read when it got the * error. */ #define GIFREAD_ERR_UNXEOF 2 /* * Bad beginning-of-file signature. Fatal. Args: none. An * application that wants to see the signature responsible should * request GIFREAD_DETAIL_SIGNATURE; the signature will be returned * with a version of GIFREAD_VERS_BAD in this case, before the * (*error)() call is made. */ #define GIFREAD_ERR_BADSIG 3 /* * Reserved values in GIF87a screen descriptor. Recovery: ignore the * unexpected values. Args: two ints. The first int is nonzero iff * the reserved 0x08 bit is set in byte [4] of the screen descriptor; * the second is nonzero iff byte [6] of the screen descriptor is not * zero. */ #define GIFREAD_ERR_87a_RESERVED 4 /* * A plain text extension had a wrong-sized header block. Recovery: * ignore the extension. Arg: one int, which holds the incorrect * header size. The ignored data blocks, starting with the * wrong-sized first block, can be obtained via * GIFREAD_DETAIL_BROKEN_EXT. */ #define GIFREAD_ERR_TEXTEXT_HDRSIZE 5 /* * A graphic control extension had a wrong-sized header block. * Recovery: ignore the extension. Arg: one int, which holds the * incorrect header size. The ignored data blocks, starting with the * wrong-sized first block, can be obtained via * GIFREAD_DETAIL_BROKEN_EXT. */ #define GIFREAD_ERR_GFXCTLEXT_HDRSIZE 6 /* * A graphic control extension had a nonzero value in the must-be-zero * high three bits of the first header byte. Recovery: ignore the * nonzero bits. Arg: one int, holding the (zero-extended) incorrect * first byte. The ignored data blocks, starting with the invalid * header block, can be obtained via GIFREAD_DETAIL_BROKEN_EXT. */ #define GIFREAD_ERR_GFXCTLEXT_MBZ 7 /* * A graphic control extension had a second data block (ie, the first * block after the header was not the zero-length extension terminator * block). Recovery: ignore the extra blocks. Arg: one int, holding * the length of the second data block. The ignored data blocks can * be obtained via GIFREAD_DETAIL_BROKEN_EXT. */ #define GIFREAD_ERR_GFXCTLEXT_BADTERM 8 /* * A graphic control extension had an invalid disposition value in its * header block. Recovery: use "none specified" instead. Arg: one * int, holding the unrecognized value of the three-bit disposition * field. */ #define GIFREAD_ERR_GFXCTLEXT_BADDISP 9 /* * A application extension had a wrong-sized header block. Recovery: * ignore the extension. Arg: one int, which holds the incorrect * header size. The ignored data blocks, starting with the * wrong-sized first block, can be obtained via * GIFREAD_DETAIL_BROKEN_EXT. */ #define GIFREAD_ERR_APPEXT_HDRSIZE 10 /* * An image descriptor has reserved bits set. Recovery: ignore the * reserved bits. Arg: one int, which holds the offending [8] octet * from the image descriptor. */ #define GIFREAD_ERR_IMGDESC_RESERVED 11 /* * An image descriptor specifies an initial code size which is not what * is expected in view of the number of bits per pixel. Recovery: use * the specified value, ignoring the expected value. Arg: two ints. * The first is the specified value, the second the expected value. */ #define GIFREAD_ERR_IMGDESC_CODESIZE 12 /* * The LZW table overflowed. Recovery: pretend a clear code occurred * and carry on. Args: none. */ #define GIFREAD_ERR_LZW_OVERFLOW 13 /* * The LZW KwKwK special case occurred without a previous code. * Recovery: ignore the invalid code and carry on. Args: none. */ #define GIFREAD_ERR_LZW_BAD_KWKWK 14 /* * An `impossible' LZW code occurred (one above the currently highest * code but below the grow-the-codesize limit). Recovery: ignore the * invalid code and carry on. Args: one int, holding the invalid * code. */ #define GIFREAD_ERR_LZW_BAD_CODE 15 /* * When a block start was expected, an octet that could not begin a * block was encountered. Recovery: skip until one is found. Args: * none. */ #define GIFREAD_ERR_SKIPJUNK 16 /* * After the GIF data straem ended, the read_input method returned more * data. Recovery: read it all. Args: none. */ #define GIFREAD_ERR_TRAILJUNK 17 /* * Bits in the third arg to gifread_open and values for the second arg * to (*detail)(). Documented here, with each bit, are (a) what * information this bit returns via (*detail)(), and (b) what the * varargs part of the (*detail)() arglist holds to pass that * information back. Except as stated, data pointed to by argument * pointers is not promised to remain valid once (*detail)() returns. */ /* * Information: raw data read from the GIF file. Args: const unsigned * char *data, int len, const char *what. data and len describe the * data block as pointer-and-length; what is a printable string * indicating what the data in question represents (such as is passed * to GIFREAD_ERR_READERROR and GIFREAD_ERR_UNXEOF errors). */ #define GIFREAD_DETAIL_DATAREAD 0x00000001 /* * Information: file header signature. Args: const unsigned char *sig, * int vers. sig is the signature itself (always six octets); vers is * one of the GIFREAD_VERS_* values from below, indicating what file * format version the library recognized the siganture as indicating. */ #define GIFREAD_DETAIL_SIGNATURE 0x00000002 /* * Information: screen descriptor. Args: w,h,m,cr,bp,bg,ar where all * args are ints. w and h are the width and height; m is the global * colourmap type, one of the GIFREAD_CMAP_* values from below; cr is * the colour resolution; bp is the bits-per-pixel (lg of the number * of colourmap entries); bg is the background colour, or a * meaningless value if m is GIFREAD_CMAP_NONE; and ar is the aspect * ratio (0 if not specified, or AR for a W:H aspect ratio of * (AR+15):64). */ #define GIFREAD_DETAIL_SCRDESC 0x00000004 /* * Information: unrecognized extension. Arg: int exttype. exttype is * the one-byte extension code of the unrecognized extension. See * GIFREAD_DETAIL_UNKEXT_DATA for the extension's data blocks. */ #define GIFREAD_DETAIL_UNKEXT 0x00000008 /* * Information: unrecognized extension data. Args: const unsigned char * *data, int len. data and len are pointer-and-length describing the * data block. The data block corresponds to the most recent * GIFREAD_DETAIL_UNKEXT call. After all the data block callbacks are * made, one callback is made with data nil and len zero. At least * one GIFREAD_DETAIL_UNKEXT_DATA call (the nil/zero terminator) is * generated for each GIFREAD_DETAIL_UNKEXT call. */ #define GIFREAD_DETAIL_UNKEXT_DATA 0x00000010 /* * Information: broken extension data. Args: const unsigned char * *data, int len. These calls are made when an extension is * encountered which is broken in some respect: an (*error)() call is * made indicating the error and then the extension data blocks are * passed back this way. After all data blocks have been returned * this way, a final call is made with data nil and len zero. */ #define GIFREAD_DETAIL_BROKEN_EXT 0x00000020 /* * Information: plain-text extension. Args: gridx,gridy,gridw,gridh, * ccw,cch,fg,bg, all unsigned ints. grid* define the grid area; ccw * and cch are the character cell width and height. fg and bg are the * foreground and background pixel values. See * GIFREAD_DETAIL_TEXTEXT_DATA for the data proper. */ #define GIFREAD_DETAIL_TEXTEXT 0x00000040 /* * Information: plain-text data. Args: const unsigned char *data, int * len. These give the data for one extension data block. After all * data blocks have been returned this way, a final call is made with * data nil and len zero. */ #define GIFREAD_DETAIL_TEXTEXT_DATA 0x00000080 /* * Information: graphic control extension. Args: four ints. In order, * they are disp, input, delay, transparent: disp is the disposition * of each image after it is displayed, as one of the * GIFREAD_GX_DISP_* values below; input is 0 or 1 according as the * file requests that user input is not or is solicited to advance to * the next image; delay is the delay, in 10ms units, before advancing * to the next image, or 0 to wait indefinitely; transparent is the * colourmap index of transparent pixels, or -1 for no transparency. */ #define GIFREAD_DETAIL_GFXCTLEXT 0x00000100 /* * Information: beginning of a comment extension. Args: none. The * data blocks are available via GIFREAD_DETAIL_COMMEXT_DATA. */ #define GIFREAD_DETAIL_COMMEXT 0x00000200 /* * Information: a comment extension data block. Args: const unsigned * char *data, int len. These specify the data block by * pointer-and-length. The list of data block calls is always * terminated by one call with data nil and len zero. */ #define GIFREAD_DETAIL_COMMEXT_DATA 0x00000400 /* * Information: beginning of an application extension. Args: a const * unsigned char * which points to 11 bytes holding the application * identifier and authentication code. The data blocks are available * via GIFREAD_DETAIL_APPEXT_DATA. */ #define GIFREAD_DETAIL_APPEXT 0x00000800 /* * Information: an application extension data block. Args: const * unsigned char *data, int len. These specify the data block by * pointer-and-length. The list of data block calls is always * terminated by one call with data nil and len zero. */ #define GIFREAD_DETAIL_APPEXT_DATA 0x00001000 /* * Information: an image descriptor. Args: x,y,w,h,m,i,b, all of which * are ints. x, y, w, and h specify the image subrectangle relative * to the screen. m is one of the GIFREAD_CMAP_* values below, * describing the local colourmap. i is an interlace indicator, 1 if * the image is interlaced and 0 if not. If m is GIFREAD_CMAP_NONE, b * is -1 and the image uses the global bits-per-pixel value; * otherwise, b is the image's bits-per-pixel. */ #define GIFREAD_DETAIL_IMGDESC 0x00002000 /* * Information: an LZW compressed data block. Args: const unsigned * char *data, int len. These describe the data block as * pointer-and-length. At end-of-data, one call is made with data nil * and len zero. */ #define GIFREAD_DETAIL_LZW_DATA 0x00004000 /* * Information: a byte of data fed into the LZW decompressor. Arg: one * int, which holds the data byte. */ #define GIFREAD_DETAIL_LZW_BYTES 0x00008000 /* * Information: an LZW codeword. Arg: two ints, the first holding the * LZW codeword and the second giving how many bits of the first are * meaningful. This call is made before checking the codeowrd; calls * for errors provoked by erroneous codewords will be made after this * call. */ #define GIFREAD_DETAIL_LZW_CODES 0x00010000 /* * Information: one pixel output from the decompressor. Arg: one int, * holding the pixel value. It is the caller's responsibility to map * this through the colourmap, if applicable and desired. */ #define GIFREAD_DETAIL_PIXELS 0x00020000 /* * Information: background. Arg: one int, holding the background pixel * value. This call is made only when there is a global colourmap, * because the field is defined to be meaningless otherwise. This * call is made only after a GIFREAD_DETAIL_CMAP call for the global * colourmap. */ #define GIFREAD_DETAIL_BACKGROUND 0x00040000 /* * Information: colourmap. This is called to give access to the * colourmap, if any. (If there is no colourmap, this call is not * made.) * * Args: int gbl, int lgents, unsigned char *ents * * gbl is 1 when the call is for the file-global colourmap, 0 if it is * for an image-local colourmap; lgents is the logarithm to base 2 of * the number of colourmap entries; ents points to 3<