Home | History | Annotate | Download | only in giflib
      1 /******************************************************************************
      2 
      3 gif_lib.h - service library for decoding and encoding GIF images
      4 
      5 *****************************************************************************/
      6 
      7 #ifndef _GIF_LIB_H_
      8 #define _GIF_LIB_H_ 1
      9 
     10 #ifdef __cplusplus
     11 extern "C" {
     12 #endif /* __cplusplus */
     13 
     14 #define GIFLIB_MAJOR 5
     15 #define GIFLIB_MINOR 1
     16 #define GIFLIB_RELEASE 1
     17 
     18 #define GIF_ERROR   0
     19 #define GIF_OK      1
     20 
     21 #include <stddef.h>
     22 #include <stdbool.h>
     23 
     24 #define GIF_STAMP "GIFVER"          /* First chars in file - GIF stamp.  */
     25 #define GIF_STAMP_LEN sizeof(GIF_STAMP) - 1
     26 #define GIF_VERSION_POS 3           /* Version first character in stamp. */
     27 #define GIF87_STAMP "GIF87a"        /* First chars in file - GIF stamp.  */
     28 #define GIF89_STAMP "GIF89a"        /* First chars in file - GIF stamp.  */
     29 
     30 typedef unsigned char GifPixelType;
     31 typedef unsigned char *GifRowType;
     32 typedef unsigned char GifByteType;
     33 typedef unsigned int GifPrefixType;
     34 typedef int GifWord;
     35 
     36 typedef struct GifColorType {
     37     GifByteType Red, Green, Blue;
     38 } GifColorType;
     39 
     40 typedef struct ColorMapObject {
     41     int ColorCount;
     42     int BitsPerPixel;
     43     bool SortFlag;
     44     GifColorType *Colors;    /* on malloc(3) heap */
     45 } ColorMapObject;
     46 
     47 typedef struct GifImageDesc {
     48     GifWord Left, Top, Width, Height;   /* Current image dimensions. */
     49     bool Interlace;                     /* Sequential/Interlaced lines. */
     50     ColorMapObject *ColorMap;           /* The local color map */
     51 } GifImageDesc;
     52 
     53 typedef struct ExtensionBlock {
     54     int ByteCount;
     55     GifByteType *Bytes; /* on malloc(3) heap */
     56     int Function;       /* The block function code */
     57 #define CONTINUE_EXT_FUNC_CODE    0x00    /* continuation subblock */
     58 #define COMMENT_EXT_FUNC_CODE     0xfe    /* comment */
     59 #define GRAPHICS_EXT_FUNC_CODE    0xf9    /* graphics control (GIF89) */
     60 #define PLAINTEXT_EXT_FUNC_CODE   0x01    /* plaintext */
     61 #define APPLICATION_EXT_FUNC_CODE 0xff    /* application block */
     62 } ExtensionBlock;
     63 
     64 typedef struct SavedImage {
     65     GifImageDesc ImageDesc;
     66     GifByteType *RasterBits;         /* on malloc(3) heap */
     67     int ExtensionBlockCount;         /* Count of extensions before image */
     68     ExtensionBlock *ExtensionBlocks; /* Extensions before image */
     69 } SavedImage;
     70 
     71 typedef struct GifFileType {
     72     GifWord SWidth, SHeight;         /* Size of virtual canvas */
     73     GifWord SColorResolution;        /* How many colors can we generate? */
     74     GifWord SBackGroundColor;        /* Background color for virtual canvas */
     75     GifByteType AspectByte;	     /* Used to compute pixel aspect ratio */
     76     ColorMapObject *SColorMap;       /* Global colormap, NULL if nonexistent. */
     77     int ImageCount;                  /* Number of current image (both APIs) */
     78     GifImageDesc Image;              /* Current image (low-level API) */
     79     SavedImage *SavedImages;         /* Image sequence (high-level API) */
     80     int ExtensionBlockCount;         /* Count extensions past last image */
     81     ExtensionBlock *ExtensionBlocks; /* Extensions past last image */
     82     int Error;			     /* Last error condition reported */
     83     void *UserData;                  /* hook to attach user data (TVT) */
     84     void *Private;                   /* Don't mess with this! */
     85 } GifFileType;
     86 
     87 #define GIF_ASPECT_RATIO(n)	((n)+15.0/64.0)
     88 
     89 typedef enum {
     90     UNDEFINED_RECORD_TYPE,
     91     SCREEN_DESC_RECORD_TYPE,
     92     IMAGE_DESC_RECORD_TYPE, /* Begin with ',' */
     93     EXTENSION_RECORD_TYPE,  /* Begin with '!' */
     94     TERMINATE_RECORD_TYPE   /* Begin with ';' */
     95 } GifRecordType;
     96 
     97 /* func type to read gif data from arbitrary sources (TVT) */
     98 typedef int (*InputFunc) (GifFileType *, GifByteType *, int);
     99 
    100 /* func type to write gif data to arbitrary targets.
    101  * Returns count of bytes written. (MRB)
    102  */
    103 typedef int (*OutputFunc) (GifFileType *, const GifByteType *, int);
    104 
    105 /******************************************************************************
    106  GIF89 structures
    107 ******************************************************************************/
    108 
    109 typedef struct GraphicsControlBlock {
    110     int DisposalMode;
    111 #define DISPOSAL_UNSPECIFIED      0       /* No disposal specified. */
    112 #define DISPOSE_DO_NOT            1       /* Leave image in place */
    113 #define DISPOSE_BACKGROUND        2       /* Set area too background color */
    114 #define DISPOSE_PREVIOUS          3       /* Restore to previous content */
    115     bool UserInputFlag;      /* User confirmation required before disposal */
    116     int DelayTime;           /* pre-display delay in 0.01sec units */
    117     int TransparentColor;    /* Palette index for transparency, -1 if none */
    118 #define NO_TRANSPARENT_COLOR	-1
    119 } GraphicsControlBlock;
    120 
    121 /******************************************************************************
    122  GIF encoding routines
    123 ******************************************************************************/
    124 
    125 /* Main entry points */
    126 GifFileType *EGifOpenFileName(const char *GifFileName,
    127                               const bool GifTestExistence, int *Error);
    128 GifFileType *EGifOpenFileHandle(const int GifFileHandle, int *Error);
    129 GifFileType *EGifOpen(void *userPtr, OutputFunc writeFunc, int *Error);
    130 int EGifSpew(GifFileType * GifFile);
    131 const char *EGifGetGifVersion(GifFileType *GifFile); /* new in 5.x */
    132 int EGifCloseFile(GifFileType *GifFile, int *ErrorCode);
    133 
    134 #define E_GIF_SUCCEEDED          0
    135 #define E_GIF_ERR_OPEN_FAILED    1    /* And EGif possible errors. */
    136 #define E_GIF_ERR_WRITE_FAILED   2
    137 #define E_GIF_ERR_HAS_SCRN_DSCR  3
    138 #define E_GIF_ERR_HAS_IMAG_DSCR  4
    139 #define E_GIF_ERR_NO_COLOR_MAP   5
    140 #define E_GIF_ERR_DATA_TOO_BIG   6
    141 #define E_GIF_ERR_NOT_ENOUGH_MEM 7
    142 #define E_GIF_ERR_DISK_IS_FULL   8
    143 #define E_GIF_ERR_CLOSE_FAILED   9
    144 #define E_GIF_ERR_NOT_WRITEABLE  10
    145 
    146 /* These are legacy.  You probably do not want to call them directly */
    147 int EGifPutScreenDesc(GifFileType *GifFile,
    148                       const int GifWidth, const int GifHeight,
    149 		      const int GifColorRes,
    150                       const int GifBackGround,
    151                       const ColorMapObject *GifColorMap);
    152 int EGifPutImageDesc(GifFileType *GifFile,
    153 		     const int GifLeft, const int GifTop,
    154                      const int GifWidth, const int GifHeight,
    155 		     const bool GifInterlace,
    156                      const ColorMapObject *GifColorMap);
    157 void EGifSetGifVersion(GifFileType *GifFile, const bool gif89);
    158 int EGifPutLine(GifFileType *GifFile, GifPixelType *GifLine,
    159                 int GifLineLen);
    160 int EGifPutPixel(GifFileType *GifFile, const GifPixelType GifPixel);
    161 int EGifPutComment(GifFileType *GifFile, const char *GifComment);
    162 int EGifPutExtensionLeader(GifFileType *GifFile, const int GifExtCode);
    163 int EGifPutExtensionBlock(GifFileType *GifFile,
    164                          const int GifExtLen, const void *GifExtension);
    165 int EGifPutExtensionTrailer(GifFileType *GifFile);
    166 int EGifPutExtension(GifFileType *GifFile, const int GifExtCode,
    167 		     const int GifExtLen,
    168                      const void *GifExtension);
    169 int EGifPutCode(GifFileType *GifFile, int GifCodeSize,
    170                 const GifByteType *GifCodeBlock);
    171 int EGifPutCodeNext(GifFileType *GifFile,
    172                     const GifByteType *GifCodeBlock);
    173 
    174 /******************************************************************************
    175  GIF decoding routines
    176 ******************************************************************************/
    177 
    178 /* Main entry points */
    179 GifFileType *DGifOpenFileName(const char *GifFileName, int *Error);
    180 GifFileType *DGifOpenFileHandle(int GifFileHandle, int *Error);
    181 int DGifSlurp(GifFileType * GifFile);
    182 GifFileType *DGifOpen(void *userPtr, InputFunc readFunc, int *Error);    /* new one (TVT) */
    183     int DGifCloseFile(GifFileType * GifFile, int *ErrorCode);
    184 
    185 #define D_GIF_SUCCEEDED          0
    186 #define D_GIF_ERR_OPEN_FAILED    101    /* And DGif possible errors. */
    187 #define D_GIF_ERR_READ_FAILED    102
    188 #define D_GIF_ERR_NOT_GIF_FILE   103
    189 #define D_GIF_ERR_NO_SCRN_DSCR   104
    190 #define D_GIF_ERR_NO_IMAG_DSCR   105
    191 #define D_GIF_ERR_NO_COLOR_MAP   106
    192 #define D_GIF_ERR_WRONG_RECORD   107
    193 #define D_GIF_ERR_DATA_TOO_BIG   108
    194 #define D_GIF_ERR_NOT_ENOUGH_MEM 109
    195 #define D_GIF_ERR_CLOSE_FAILED   110
    196 #define D_GIF_ERR_NOT_READABLE   111
    197 #define D_GIF_ERR_IMAGE_DEFECT   112
    198 #define D_GIF_ERR_EOF_TOO_SOON   113
    199 
    200 /* These are legacy.  You probably do not want to call them directly */
    201 int DGifGetScreenDesc(GifFileType *GifFile);
    202 int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType);
    203 int DGifGetImageDesc(GifFileType *GifFile);
    204 int DGifGetLine(GifFileType *GifFile, GifPixelType *GifLine, int GifLineLen);
    205 int DGifGetPixel(GifFileType *GifFile, GifPixelType GifPixel);
    206 int DGifGetComment(GifFileType *GifFile, char *GifComment);
    207 int DGifGetExtension(GifFileType *GifFile, int *GifExtCode,
    208                      GifByteType **GifExtension);
    209 int DGifGetExtensionNext(GifFileType *GifFile, GifByteType **GifExtension);
    210 int DGifGetCode(GifFileType *GifFile, int *GifCodeSize,
    211                 GifByteType **GifCodeBlock);
    212 int DGifGetCodeNext(GifFileType *GifFile, GifByteType **GifCodeBlock);
    213 int DGifGetLZCodes(GifFileType *GifFile, int *GifCode);
    214 
    215 
    216 /******************************************************************************
    217  Color table quantization (deprecated)
    218 ******************************************************************************/
    219 int GifQuantizeBuffer(unsigned int Width, unsigned int Height,
    220                    int *ColorMapSize, GifByteType * RedInput,
    221                    GifByteType * GreenInput, GifByteType * BlueInput,
    222                    GifByteType * OutputBuffer,
    223                    GifColorType * OutputColorMap);
    224 
    225 /******************************************************************************
    226  Error handling and reporting.
    227 ******************************************************************************/
    228 extern const char *GifErrorString(int ErrorCode);     /* new in 2012 - ESR */
    229 
    230 /*****************************************************************************
    231  Everything below this point is new after version 1.2, supporting `slurp
    232  mode' for doing I/O in two big belts with all the image-bashing in core.
    233 ******************************************************************************/
    234 
    235 /******************************************************************************
    236  Color map handling from gif_alloc.c
    237 ******************************************************************************/
    238 
    239 extern ColorMapObject *GifMakeMapObject(int ColorCount,
    240                                      const GifColorType *ColorMap);
    241 extern void GifFreeMapObject(ColorMapObject *Object);
    242 extern ColorMapObject *GifUnionColorMap(const ColorMapObject *ColorIn1,
    243                                      const ColorMapObject *ColorIn2,
    244                                      GifPixelType ColorTransIn2[]);
    245 extern int GifBitSize(int n);
    246 
    247 /******************************************************************************
    248  Support for the in-core structures allocation (slurp mode).
    249 ******************************************************************************/
    250 
    251 extern void GifApplyTranslation(SavedImage *Image, GifPixelType Translation[]);
    252 extern int GifAddExtensionBlock(int *ExtensionBlock_Count,
    253 				ExtensionBlock **ExtensionBlocks,
    254 				int Function,
    255 				unsigned int Len, unsigned char ExtData[]);
    256 extern void GifFreeExtensions(int *ExtensionBlock_Count,
    257 			      ExtensionBlock **ExtensionBlocks);
    258 extern SavedImage *GifMakeSavedImage(GifFileType *GifFile,
    259                                   const SavedImage *CopyFrom);
    260 extern void GifFreeSavedImages(GifFileType *GifFile);
    261 
    262 /******************************************************************************
    263  5.x functions for GIF89 graphics control blocks
    264 ******************************************************************************/
    265 
    266 int DGifExtensionToGCB(const size_t GifExtensionLength,
    267 		       const GifByteType *GifExtension,
    268 		       GraphicsControlBlock *GCB);
    269 size_t EGifGCBToExtension(const GraphicsControlBlock *GCB,
    270 		       GifByteType *GifExtension);
    271 
    272 int DGifSavedExtensionToGCB(GifFileType *GifFile,
    273 			    int ImageIndex,
    274 			    GraphicsControlBlock *GCB);
    275 int EGifGCBToSavedExtension(const GraphicsControlBlock *GCB,
    276 			    GifFileType *GifFile,
    277 			    int ImageIndex);
    278 
    279 /******************************************************************************
    280  The library's internal utility font
    281 ******************************************************************************/
    282 
    283 #define GIF_FONT_WIDTH  8
    284 #define GIF_FONT_HEIGHT 8
    285 extern const unsigned char GifAsciiTable8x8[][GIF_FONT_WIDTH];
    286 
    287 extern void GifDrawText8x8(SavedImage *Image,
    288                      const int x, const int y,
    289                      const char *legend, const int color);
    290 
    291 extern void GifDrawBox(SavedImage *Image,
    292                     const int x, const int y,
    293                     const int w, const int d, const int color);
    294 
    295 extern void GifDrawRectangle(SavedImage *Image,
    296                    const int x, const int y,
    297                    const int w, const int d, const int color);
    298 
    299 extern void GifDrawBoxedText8x8(SavedImage *Image,
    300                           const int x, const int y,
    301                           const char *legend,
    302                           const int border, const int bg, const int fg);
    303 
    304 #ifdef __cplusplus
    305 }
    306 #endif /* __cplusplus */
    307 #endif /* _GIF_LIB_H */
    308 
    309 /* end */
    310