text: /**
   * @file gifread.h
   * A simple GIF reader.
   *
   * @author Cosmin Truta
   *
   * @section Copyright
   * Copyright (C) 2003-2011 Cosmin Truta.
   * This software was derived from "giftopnm.c" by David Koblas,
   * and is distributed under the same copyright and warranty terms.
   *
   * The original copyright notice is provided below.
   * <pre>
   * +-------------------------------------------------------------------+
   * | Copyright 1990, 1991, 1993, David Koblas.  (koblas@netcom.com)    |
   * |   Permission to use, copy, modify, and distribute this software   |
   * |   and its documentation for any purpose and without fee is hereby |
   * |   granted, provided that the above copyright notice appear in all |
   * |   copies and that both that copyright notice and this permission  |
   * |   notice appear in supporting documentation.  This software is    |
   * |   provided "as is" without express or implied warranty.           |
   * +-------------------------------------------------------------------+
   * </pre>
   **/
  
  #ifndef GIFREAD_H
  #define GIFREAD_H
  
  #include <stdio.h>
  
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  
  #define GIF_PLAINTEXT   0x01
  #define GIF_EXTENSION   0x21  /* '!' */
  #define GIF_IMAGE       0x2c  /* ',' */
  #define GIF_TERMINATOR  0x3b  /* ';' */
  #define GIF_GRAPHICCTL  0xf9
  #define GIF_COMMENT     0xfe
  #define GIF_APPLICATION 0xff
  
  #define GIF_NUMCOLORS_MAX 256
  
  #define GIF_IND_RED   0
  #define GIF_IND_GREEN 1
  #define GIF_IND_BLUE  2
  
  
  /**
   * The GIF screen structure.
   **/
  struct GIFScreen
  {
      unsigned int  Width;
      unsigned int  Height;
      unsigned int  GlobalColorFlag;
      unsigned int  ColorResolution;
      unsigned int  SortFlag;
      unsigned int  GlobalNumColors;
      unsigned int  Background;
      unsigned int  PixelAspectRatio;
      unsigned char GlobalColorTable[GIF_NUMCOLORS_MAX * 3];
  };
  
  /**
   * The GIF image structure.
   **/
  struct GIFImage
  {
      struct GIFScreen *Screen;
      unsigned int  LeftPos;
      unsigned int  TopPos;
      unsigned int  Width;
      unsigned int  Height;
      unsigned int  LocalColorFlag;
      unsigned int  InterlaceFlag;
      unsigned int  SortFlag;
      unsigned int  LocalNumColors;
      unsigned char LocalColorTable[GIF_NUMCOLORS_MAX * 3];
      unsigned char **Rows;
  };
  
  /**
   * The GIF extension structure.
   **/
  struct GIFExtension
  {
      struct GIFScreen *Screen;
      unsigned char *Buffer;
      unsigned int  BufferSize;
      unsigned char Label;
  };
  
  /**
   * The GIF graphic control extension structure.
   **/
  struct GIFGraphicCtlExt
  {
      unsigned int DisposalMethod;
      unsigned int InputFlag;
      unsigned int TransparentFlag;
      unsigned int DelayTime;
      unsigned int Transparent;
  };
  
  
  /**
   * Reads the GIF screen and the global color table.
   * @param screen  the destination screen.
   * @param stream  a file stream.
   **/
  void GIFReadScreen(struct GIFScreen *screen, FILE *stream);
  
  /**
   * Initializes a GIF image object.
   * @param image   the resulting image.
   * @param screen  a screen.
   * @param rows    an array of rows; can be NULL.
   **/
  void GIFInitImage(struct GIFImage *image,
                    struct GIFScreen *screen, unsigned char **rows);
  
  /**
   * Destroys a GIF image object.
   * @param image  an image.
   **/
  void GIFDestroyImage(struct GIFImage *image);
  
  /**
   * Reads the next GIF block into an image or extension object.
   * @param image   the destination image; can be NULL.
   * @param ext     the destination extension; can be NULL.
   * @param stream  a file stream.
   * @return        the block code or EOF.
   **/
  int GIFReadNextBlock(struct GIFImage *image, struct GIFExtension *ext,
                       FILE *stream);
  
  /**
   * Returns the local or the global color table (whichever is applicable),
   * or a predefined color table if both of these tables are missing.
   * @param colors     the resulting color table.
   * @param numColors  the size of the resulting color table.
   * @param image      an image.
   **/
  void GIFGetColorTable(unsigned char **colors, unsigned int *numColors,
                        struct GIFImage *image);
  
  /**
   * Initializes a GIF extension object.
   * @param ext             the resulting extension.
   * @param screen          a screen.
   * @param initBufferSize  an initial buffer size; can be 0.
   **/
  void GIFInitExtension(struct GIFExtension *ext,
                        struct GIFScreen *screen, unsigned int initBufferSize);
  
  /**
   * Destroys a GIF extension object.
   * @param ext  an extension.
   **/
  void GIFDestroyExtension(struct GIFExtension *ext);
  
  /**
   * Constructs a GIF graphic control extension object
   * from a raw extension object.
   * @param graphicExt  the resulting graphic control extension.
   * @param ext         a raw extension.
   **/
  void GIFGetGraphicCtl(struct GIFGraphicCtlExt *graphicExt,
                        struct GIFExtension *ext);
  
  
  /**
   * The error handling callback.
   * @param message  an error message.
   **/
  extern void (*GIFError)(const char *message);
  
  /**
   * The warning handling callback.
   * @param message  a warning message.
   **/
  extern void (*GIFWarning)(const char *message);
  
  
  #ifdef __cplusplus
  }  /* extern "C" */
  #endif
  
  
  #endif  /* GIFREAD_H */
  