Dali: GIF -- C API

Header Files

#include <dvmgif.h>

Type Definitions

GifSeqHdr

The struct GifSeqHdr corresponds to what the GIF standards refer to as the header and logical screen descriptor.

      typedef struct GifSeqHdr {
          int ctFlag;    
          int bitsPerPixel;            
          int ctSize;
          int ctSorted;      
          int width;     
          int height;    
          int resolution;   
          int backgroundColor;
          int aspectRatio;    
          char version[3];           
      } GifSeqHdr;

ctFlag

1 if the sequence has a global color table, 0 otherwise.

bitsPerPixel

The number of bits per pixel of each color table entry.

ctSize

The size of the global color table. This is equal to 2^(bitsPerPixel) and the maximum size is 256.

ctSorted

1 if the global color table is sorted, 0 otherwise. Typically the color table is sorted in descreasing order of frequency.

width

Width of each frame in pixels.

height

Height of each frame in pixels.

resolution

Number of bits per primary color available to the original image.

backgroundColor

Index in the global color table of background color.

aspectRatio

Pixel aspect ratio.

version

The GIF version to which the sequence conforms. This is usually "87a" or "89a".

GifImgHdr

The struct GifImgHdr corresponds to what the GIF standards refers to as the image descriptor and graphic control extension.

      typedef struct GifImgHdr {
          int ctFlag;    
          int bitsPerPixel;            
          int ctSize;
          int ctSorted;       
          int leftPosition;
          int topPosition;
          int width;
          int height;
          int interlaced;
          int graphicControlFlag;
          int disposalMethod;
          int userInputFlag;
          int transparentColorFlag;
          int delayTime;
          int transparentColorIndex;
      } GifImgHdr;

ctFlag

1 if the image has a local color table. 0 if local color table is not present.

bitsPerPixel

The number of bits per pixel of each color table entry. This is valid only if ctFlag is 1.

ctSize

The size of the local color table. This is equal to 2^(bitsPerPixel) and the maximum size is 256. This is valid only if ctFlag is 1.

ctSorted

Whether the local color table is sorted or not. This is valid only if ctFlag is 1.

leftPosition, topPosition

Position (in pixel) of this image with respect to the GIF image.

width

Width of the image in pixels.

height

Height of the image in pixels.

interlaced

1 if the image is interlaced, 0 otherwise.

graphicControlFlag

1 if the image has a graphic control extension, 0 otherwise. The graphic control extension is available for GIF version "89a" only.

disposalMethod

Indicates the way in which the graphic is to be treated after being displayed. Possible values:

0 - No disposal specified.
1 - Do not dispose.
2 - Restore to background color.
3 - Restore to previous.
This is valid only if graphic control flag is 1.

userInputFlag

Indicates whether or not user input is expected before continuing. This is valid only if graphic control flag is 1.

transparentColorFlag

Indicates whether a transparency index is given in the Transparent Index field. This is valid only if graphic control flag is 1.

delayTime

If not 0, this field specifies the number of hundredths (1/100) of a second to wait before continuing with the processing of the Data Stream. This is valid only if graphic control flag is 1.

transparentColorIndex

When encountered, the corresponding pixel of the display device is not modified and processing goes on to the next pixel, if the transparent color flag is set. This is valid only if graphic control flag is 1.

Constants

Return Code

Return code from various GIF primitives. GIF_OK indicates the primitives executed succesfully. IMG_READ_ERROR indicates some occured while reading the GIF Image. IMG_SEPARATOR_ERROR indicates an invalid GIF image header. BAD_HEADER indicates there is an error in the GIF signature of the sequence header. BAD_VERSION indicates an invalid version number in the sequence header.

    #define DVM_GIF_OK 0
    #define DVM_GIF_IMG_READ_ERROR -1
    #define DVM_GIF_EOF_ERROR -2
    #define DVM_GIF_IMG_SEPARATOR_ERROR -3
    #define DVM_GIF_BAD_HEADER -4
    #define DVM_GIF_BAD_VERSION -5
    #define DVM_GIF_INTERLACED -6
    #define DVM_GIF_NOT_INTERLACED -7
    #define DVM_GIF_BAD_WIDTH -8
    #define DVM_GIF_BAD_HEIGHT -9

Operators

Allocation and Deallcation Primitives

GifSeqHdr *GifSeqHdrNew ()

Allocate a new GIF sequence header.

void GifSeqHdrFree (GifSeqHdr *hdr)

Frees the memory allocated for the GIF sequence header hdr.

GifImgHdr *GifImgHdrNew ()

Allocate a new GIF Image Header.

void GifImgHdrFree (GifImgHdr *hdr)

Deallocate the GifImgHdr pointed to by hdr.

GIF Decoding Primtives

int GifSeqHdrParse (BitParser* bp, GifSeqHdr* gifHdr)

Assuming that the corresponding BitStreams position is at the beginning of a GIF file, BitParser bp will parse its BitStream and initialize the sequence header structure hdr. After parsing, the BitParser's current bit position is right after the end of the sequence header.

int GifCtParse(BitParser* bp, int size, ImageMap *red, ImageMap *green, ImageMap *blue);

Assuming the BitParser bp is pointing to the beginning of a color table (global or local) of size size, parse the color table into the three ImageMaps. The BitParser's new position will be immediately following the color table.

int GifImgHdrParse (BitParser *bp, GifImgHdr *hdr)

Assuming that the corresponding BitStreams position is at the beginning of a GIF image header (an image DESCRIPTOR or a graphical control extension), BitParser bp will parse its BitStream and initialize the GIF image header structure hdr. After parsing, the BitParser's current bit position is right after the end of the image header.

int GifImgInterlacedParse (BitParser *bp, GifSeqHdr *seqHdr, GifImgHdr *imgHdr, ByteImage *mapBuf)

Assuming that the corresponding BitStream's position is at the beginning of an interlaced image data, BitParser bp will parse its BitStream and initialize the ByteImage mapBuf with ColorTable indices corresponding to the ImageMaps containing the ColorTable data. After parsing, the BitParser's current bit position is immediately following the end of the image data.

int GifImgNoneInterlacedParse (BitParser *bp, GifSeqHdr *seqHdr, GifImgHdr *imgHdr, ByteImage *mapBuf)

Assuming that the corresponding BitStream's position is at the beginning of a non-interlaced image data, BitParser bp will parse its BitStream and initialize the ByteImage mapBuf with ColorTable indices corresponding to the ImageMaps containing the ColorTable data. After parsing, the BitParser's current bit position is immediately following the end of the image data.

GIF Encoding Primtives

void GifSeqHdrEncode(BitParser* bp, GifSeqHdr *gifHdr)

Encodes the content of the sequence header gifHdr to the output BitStream attached to BitParser bp.

void GifSeqLoopEncode(BitParser *bp)

Encodes the Netscape application header that indicates the the animated GIF sequence should be played in a loop.

void GifSeqTrailerEncode(BitParser* bp)

Encodes a GIF_TRAILER, indicating the end of a GIF sequence.

void GifCtEncode(int size, ImageMap *red, ImageMap *green, ImageMap *blue, BitParser* bp);

Encodes the contents of the three ImageMaps to the position in the BitStream pointed to by BitParser bp.

void GifImgHdrEncode (GifImgHdr *hdr, BitParser *bp)

Encodes the content of the picture header hdr to the output BitStream attached to BitParser bp.

void GifImgEncode(GifImgHdr* imgHdr, BitParser* bp)

Encodes the Color Table indices in ByteImage buf using BitParser bp.

GIF Sequence Header Queries

int GifSeqHdrGetWidth(GifSeqHdr* seqHdr) int GifSeqHdrGetHeight(GifSeqHdr* seqHdr) int GifSeqHdrGetCtFlag(GifSeqHdr* seqHdr) int GifSeqHdrGetCtSize(GifSeqHdr* seqHdr) int GifSeqHdrGetCtSorted(GifSeqHdr* seqHdr) int GifSeqHdrGetResolution(GifSeqHdr* seqHdr) int GifSeqHdrGetBackgroundColor(GifSeqHdr* seqHdr) int GifSeqHdrGetAspectRatio(GifSeqHdr* seqHdr) int GifSeqHdrGetVersion(GifSeqHdr* seqHdr)

These information operations return the fields of the GIF sequence header.

GIF Sequence Header Initialization

void GifSeqHdrSetWidth(GifSeqHdr* seqHdr, void width) void GifSeqHdrSetHeight(GifSeqHdr* seqHdr, void height) void GifSeqHdrSetCtFlag(GifSeqHdr* seqHdr, void ct_flag) void GifSeqHdrSetCtSize(GifSeqHdr* seqHdr, void ct_size) void GifSeqHdrSetCtSorted(GifSeqHdr* seqHdr, void ct_sorted) void GifSeqHdrSetResolution(GifSeqHdr* seqHdr, void resolution) void GifSeqHdrSetBackgroundColor(GifSeqHdr* seqHdr, void background_color) void GifSeqHdrSetAspectRatio(GifSeqHdr* seqHdr, void aspect_ratio) void GifSeqHdrSetVersion(GifSeqHdr* seqHdr, char* version)

These primtives intializate various fields in the GIF sequence header. These operations are defined as macros.

GifImgHdr Queries

int GifImgHdrGetWidth(GifImgHdr *imgHdr) int GifImgHdrGetHeight(GifImgHdr *imgHdr) int GifImgHdrGetCtFlag(GifImgHdr *imgHdr) int GifImgHdrGetBitsPerPixel(GifImgHdr *imgHdr) int GifImgHdrGetCtSize(GifImgHdr *imgHdr) int GifImgHdrGetLeftPosition(GifImgHdr *imgHdr) int GifImgHdrGetTopPosition(GifImgHdr *imgHdr) int GifImgHdrGetInterlaced(GifImgHdr *imgHdr) int GifImgHdrGetGraphicControlFlag(GifImgHdr *imgHdr) int GifImgHdrGetDisposalMethod(GifImgHdr *imgHdr) int GifImgHdrGetUserInputFlag(GifImgHdr *imgHdr) int GifImgHdrGetTransparentColorFlag(GifImgHdr *imgHdr) int GifImgHdrGetDelayTime(GifImgHdr *imgHdr) int GifImgHdrGetTransparentColorIndex(GifImgHdr *imgHdr)

These information operations return the corresponding fields in the GIF image header. These operations are defined as macros.

GifImgHdr Initialization

void GifImgHdrSetWidth(GifImgHdr *imgHdr, width) void GifImgHdrSetHeight(GifImgHdr *imgHdr, height) void GifImgHdrSetCtFlag(GifImgHdr *imgHdr, ct_flag) void GifImgHdrSetBitsPerPixel(GifImgHdr *imgHdr, bits_per_pixel) void GifImgHdrSetCtSize(GifImgHdr *imgHdr, ct_size) void GifImgHdrSetLeftPosition(GifImgHdr *imgHdr, left_position) void GifImgHdrSetTopPosition(GifImgHdr *imgHdr, top_position) void GifImgHdrSetInterlaced(GifImgHdr *imgHdr, interlaced) void GifImgHdrSetGraphicControlFlag(GifImgHdr *imgHdr, graphic_control_flag) void GifImgHdrSetDisposalMethod(GifImgHdr *imgHdr, disposal_method) void GifImgHdrSetUserInputFlag(GifImgHdr *imgHdr, user_input_flag) void GifImgHdrSetTransparentColorFlag(GifImgHdr *imgHdr, transparent_color_flag) void GifImgHdrSetDelayTime(GifImgHdr *imgHdr, delay_time) void GifImgHdrSetTransparentColorIndex(GifImgHdr *imgHdr, transparent_color_index)

These initialization primitives set the fields in the GIF image header. These operations are defined as macros.

GIF Image Primitives

int GifImgSkip (BitParser *bp)

Assuming the BitParser bp positioned at the beginning of an image header, skips the image. The BitParser's current bit position is set to the start of the next image header, or the GIF sequence trailer.

int GifImgFind (BitParser *bp)

Advances the BitParser bp to the beginning of the next GIF image header (by finding GIF_IMG_SEPARATOR or GIF_GRAPHIC_CONTROL_LABEL in the BitStream it is attached to). Returns DVM_GIF_OK if successful, or DVM_GIF_EOF_ERROR if a GIF_TRAILER is found first.