source/include/gif_lib.h

0001 /******************************************************************************
0002
0003 gif_lib.h - service library for decoding and encoding GIF images
0004
0005 SPDX-License-Identifier: MIT
0006
0007 *****************************************************************************/
0008
0009 #ifndef _GIF_LIB_H_
0010 #define _GIF_LIB_H_ 1
0011
0012 #ifdef __cplusplus
0013 extern "C" {
0014 #endif /* __cplusplus */
0015
0016 #define GIFLIB_MAJOR 5
0017 #define GIFLIB_MINOR 2
0018 #define GIFLIB_RELEASE 2
0019
0020 #define GIF_ERROR 0
0021 #define GIF_OK 1
0022
0023 #include <stdbool.h>
0024 #include <stddef.h>
0025
0026 #define GIF_STAMP "GIFVER" /* First chars in file - GIF stamp.  */
0027 #define GIF_STAMP_LEN sizeof(GIF_STAMP) - 1
0028 #define GIF_VERSION_POS 3    /* Version first character in stamp. */
0029 #define GIF87_STAMP "GIF87a" /* First chars in file - GIF stamp.  */
0030 #define GIF89_STAMP "GIF89a" /* First chars in file - GIF stamp.  */
0031
0032 typedef unsigned char GifPixelType;
0033 typedef unsigned char *GifRowType;
0034 typedef unsigned char GifByteType;
0035 typedef unsigned int GifPrefixType;
0036 typedef int GifWord;
0037
0038 typedef struct GifColorType {
0039     GifByteType Red, Green, Blue;
0040 } GifColorType;
0041
0042 typedef struct ColorMapObject {
0043     int ColorCount;
0044     int BitsPerPixel;
0045     bool SortFlag;
0046     GifColorType *Colors; /* on malloc(3) heap */
0047 } ColorMapObject;
0048
0049 typedef struct GifImageDesc {
0050     GifWord Left, Top, Width, Height; /* Current image dimensions. */
0051     bool Interlace;                   /* Sequential/Interlaced lines. */
0052     ColorMapObject *ColorMap;         /* The local color map */
0053 } GifImageDesc;
0054
0055 typedef struct ExtensionBlock {
0056     int ByteCount;
0057     GifByteType *Bytes;            /* on malloc(3) heap */
0058     int Function;                  /* The block function code */
0059 #define CONTINUE_EXT_FUNC_CODE 0x00    /* continuation subblock */
0060 #define COMMENT_EXT_FUNC_CODE 0xfe     /* comment */
0061 #define GRAPHICS_EXT_FUNC_CODE 0xf9    /* graphics control (GIF89) */
0062 #define PLAINTEXT_EXT_FUNC_CODE 0x01   /* plaintext */
0063 #define APPLICATION_EXT_FUNC_CODE 0xff /* application block (GIF89) */
0064 } ExtensionBlock;
0065
0066 typedef struct SavedImage {
0067     GifImageDesc ImageDesc;
0068     GifByteType *RasterBits;         /* on malloc(3) heap */
0069     int ExtensionBlockCount;         /* Count of extensions before image */
0070     ExtensionBlock *ExtensionBlocks; /* Extensions before image */
0071 } SavedImage;
0072
0073 typedef struct GifFileType {
0074     GifWord SWidth, SHeight;   /* Size of virtual canvas */
0075     GifWord SColorResolution;  /* How many colors can we generate? */
0076     GifWord SBackGroundColor;  /* Background color for virtual canvas */
0077     GifByteType AspectByte;    /* Used to compute pixel aspect ratio */
0078     ColorMapObject *SColorMap; /* Global colormap, NULL if nonexistent. */
0079     int ImageCount;            /* Number of current image (both APIs) */
0080     GifImageDesc Image;        /* Current image (low-level API) */
0081     SavedImage *SavedImages;   /* Image sequence (high-level API) */
0082     int ExtensionBlockCount;   /* Count extensions past last image */
0083     ExtensionBlock *ExtensionBlocks; /* Extensions past last image */
0084     int Error;                       /* Last error condition reported */
0085     void *UserData;                  /* hook to attach user data (TVT) */
0086     void *Private;                   /* Don't mess with this! */
0087 } GifFileType;
0088
0089 #define GIF_ASPECT_RATIO(n) ((n) + 15.0 / 64.0)
0090
0091 typedef enum {
0092     UNDEFINED_RECORD_TYPE,
0093     SCREEN_DESC_RECORD_TYPE,
0094     IMAGE_DESC_RECORD_TYPE, /* Begin with ',' */
0095     EXTENSION_RECORD_TYPE,  /* Begin with '!' */
0096     TERMINATE_RECORD_TYPE   /* Begin with ';' */
0097 } GifRecordType;
0098
0099 /* func type to read gif data from arbitrary sources (TVT) */
0100 typedef int (*InputFunc)(GifFileType *, GifByteType *, int);
0101
0102 /* func type to write gif data to arbitrary targets.
0103  * Returns count of bytes written. (MRB)
0104  */
0105 typedef int (*OutputFunc)(GifFileType *, const GifByteType *, int);
0106
0107 /******************************************************************************
0108  GIF89 structures
0109 ******************************************************************************/
0110
0111 typedef struct GraphicsControlBlock {
0112     int DisposalMode;
0113 #define DISPOSAL_UNSPECIFIED 0 /* No disposal specified. */
0114 #define DISPOSE_DO_NOT 1       /* Leave image in place */
0115 #define DISPOSE_BACKGROUND 2   /* Set area too background color */
0116 #define DISPOSE_PREVIOUS 3     /* Restore to previous content */
0117     bool UserInputFlag;    /* User confirmation required before disposal */
0118     int DelayTime;         /* pre-display delay in 0.01sec units */
0119     int TransparentColor;  /* Palette index for transparency, -1 if none */
0120 #define NO_TRANSPARENT_COLOR -1
0121 } GraphicsControlBlock;
0122
0123 /******************************************************************************
0124  GIF encoding routines
0125 ******************************************************************************/
0126
0127 /* Main entry points */
0128 GifFileType *EGifOpenFileName(const char *GifFileName,
0129                               const bool GifTestExistence, int *Error);
0130 GifFileType *EGifOpenFileHandle(const int GifFileHandle, int *Error);
0131 GifFileType *EGifOpen(void *userPtr, OutputFunc writeFunc, int *Error);
0132 int EGifSpew(GifFileType *GifFile);
0133 const char *EGifGetGifVersion(GifFileType *GifFile); /* new in 5.x */
0134 int EGifCloseFile(GifFileType *GifFile, int *ErrorCode);
0135
0136 #define E_GIF_SUCCEEDED 0
0137 #define E_GIF_ERR_OPEN_FAILED 1 /* And EGif possible errors. */
0138 #define E_GIF_ERR_WRITE_FAILED 2
0139 #define E_GIF_ERR_HAS_SCRN_DSCR 3
0140 #define E_GIF_ERR_HAS_IMAG_DSCR 4
0141 #define E_GIF_ERR_NO_COLOR_MAP 5
0142 #define E_GIF_ERR_DATA_TOO_BIG 6
0143 #define E_GIF_ERR_NOT_ENOUGH_MEM 7
0144 #define E_GIF_ERR_DISK_IS_FULL 8
0145 #define E_GIF_ERR_CLOSE_FAILED 9
0146 #define E_GIF_ERR_NOT_WRITEABLE 10
0147
0148 /* These are legacy.  You probably do not want to call them directly */
0149 int EGifPutScreenDesc(GifFileType *GifFile, const int GifWidth,
0150                       const int GifHeight, const int GifColorRes,
0151                       const int GifBackGround,
0152                       const ColorMapObject *GifColorMap);
0153 int EGifPutImageDesc(GifFileType *GifFile, const int GifLeft, const int GifTop,
0154                      const int GifWidth, const int GifHeight,
0155                      const bool GifInterlace,
0156                      const ColorMapObject *GifColorMap);
0157 void EGifSetGifVersion(GifFileType *GifFile, const bool gif89);
0158 int EGifPutLine(GifFileType *GifFile, GifPixelType *GifLine, int GifLineLen);
0159 int EGifPutPixel(GifFileType *GifFile, const GifPixelType GifPixel);
0160 int EGifPutComment(GifFileType *GifFile, const char *GifComment);
0161 int EGifPutExtensionLeader(GifFileType *GifFile, const int GifExtCode);
0162 int EGifPutExtensionBlock(GifFileType *GifFile, const int GifExtLen,
0163                           const void *GifExtension);
0164 int EGifPutExtensionTrailer(GifFileType *GifFile);
0165 int EGifPutExtension(GifFileType *GifFile, const int GifExtCode,
0166                      const int GifExtLen, const void *GifExtension);
0167 int EGifPutCode(GifFileType *GifFile, int GifCodeSize,
0168                 const GifByteType *GifCodeBlock);
0169 int EGifPutCodeNext(GifFileType *GifFile, const GifByteType *GifCodeBlock);
0170
0171 /******************************************************************************
0172  GIF decoding routines
0173 ******************************************************************************/
0174
0175 /* Main entry points */
0176 GifFileType *DGifOpenFileName(const char *GifFileName, int *Error);
0177 GifFileType *DGifOpenFileHandle(int GifFileHandle, int *Error);
0178 int DGifSlurp(GifFileType *GifFile);
0179 GifFileType *DGifOpen(void *userPtr, InputFunc readFunc,
0180                       int *Error); /* new one (TVT) */
0181 int DGifCloseFile(GifFileType *GifFile, int *ErrorCode);
0182
0183 #define D_GIF_SUCCEEDED 0
0184 #define D_GIF_ERR_OPEN_FAILED 101 /* And DGif possible errors. */
0185 #define D_GIF_ERR_READ_FAILED 102
0186 #define D_GIF_ERR_NOT_GIF_FILE 103
0187 #define D_GIF_ERR_NO_SCRN_DSCR 104
0188 #define D_GIF_ERR_NO_IMAG_DSCR 105
0189 #define D_GIF_ERR_NO_COLOR_MAP 106
0190 #define D_GIF_ERR_WRONG_RECORD 107
0191 #define D_GIF_ERR_DATA_TOO_BIG 108
0192 #define D_GIF_ERR_NOT_ENOUGH_MEM 109
0193 #define D_GIF_ERR_CLOSE_FAILED 110
0194 #define D_GIF_ERR_NOT_READABLE 111
0195 #define D_GIF_ERR_IMAGE_DEFECT 112
0196 #define D_GIF_ERR_EOF_TOO_SOON 113
0197
0198 /* These are legacy.  You probably do not want to call them directly */
0199 int DGifGetScreenDesc(GifFileType *GifFile);
0200 int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType);
0201 int DGifGetImageHeader(GifFileType *GifFile);
0202 int DGifGetImageDesc(GifFileType *GifFile);
0203 int DGifGetLine(GifFileType *GifFile, GifPixelType *GifLine, int GifLineLen);
0204 int DGifGetPixel(GifFileType *GifFile, GifPixelType GifPixel);
0205 int DGifGetExtension(GifFileType *GifFile, int *GifExtCode,
0206                      GifByteType **GifExtension);
0207 int DGifGetExtensionNext(GifFileType *GifFile, GifByteType **GifExtension);
0208 int DGifGetCode(GifFileType *GifFile, int *GifCodeSize,
0209                 GifByteType **GifCodeBlock);
0210 int DGifGetCodeNext(GifFileType *GifFile, GifByteType **GifCodeBlock);
0211 int DGifGetLZCodes(GifFileType *GifFile, int *GifCode);
0212 const char *DGifGetGifVersion(GifFileType *GifFile);
0213
0214 /******************************************************************************
0215  Error handling and reporting.
0216 ******************************************************************************/
0217 extern const char *GifErrorString(int ErrorCode); /* new in 2012 - ESR */
0218
0219 /*****************************************************************************
0220  Everything below this point is new after version 1.2, supporting `slurp
0221  mode' for doing I/O in two big belts with all the image-bashing in core.
0222 ******************************************************************************/
0223
0224 /******************************************************************************
0225  Color map handling from gif_alloc.c
0226 ******************************************************************************/
0227
0228 extern ColorMapObject *GifMakeMapObject(int ColorCount,
0229                                         const GifColorType *ColorMap);
0230 extern void GifFreeMapObject(ColorMapObject *Object);
0231 extern ColorMapObject *GifUnionColorMap(const ColorMapObject *ColorIn1,
0232                                         const ColorMapObject *ColorIn2,
0233                                         GifPixelType ColorTransIn2[]);
0234 extern int GifBitSize(int n);
0235
0236 /******************************************************************************
0237  Support for the in-core structures allocation (slurp mode).
0238 ******************************************************************************/
0239
0240 extern void GifApplyTranslation(SavedImage *Image,
0241                                 const GifPixelType Translation[]);
0242 extern int GifAddExtensionBlock(int *ExtensionBlock_Count,
0243                                 ExtensionBlock **ExtensionBlocks, int Function,
0244                                 unsigned int Len, unsigned char ExtData[]);
0245 extern void GifFreeExtensions(int *ExtensionBlock_Count,
0246                               ExtensionBlock **ExtensionBlocks);
0247 extern SavedImage *GifMakeSavedImage(GifFileType *GifFile,
0248                                      const SavedImage *CopyFrom);
0249 extern void GifFreeSavedImages(GifFileType *GifFile);
0250
0251 /******************************************************************************
0252  5.x functions for GIF89 graphics control blocks
0253 ******************************************************************************/
0254
0255 int DGifExtensionToGCB(const size_t GifExtensionLength,
0256                        const GifByteType *GifExtension,
0257                        GraphicsControlBlock *GCB);
0258 size_t EGifGCBToExtension(const GraphicsControlBlock *GCB,
0259                           GifByteType *GifExtension);
0260
0261 int DGifSavedExtensionToGCB(GifFileType *GifFile, int ImageIndex,
0262                             GraphicsControlBlock *GCB);
0263 int EGifGCBToSavedExtension(const GraphicsControlBlock *GCB,
0264                             GifFileType *GifFile, int ImageIndex);
0265
0266 /******************************************************************************
0267  The library's internal utility font
0268 ******************************************************************************/
0269
0270 #define GIF_FONT_WIDTH 8
0271 #define GIF_FONT_HEIGHT 8
0272 extern const unsigned char GifAsciiTable8x8[][GIF_FONT_WIDTH];
0273
0274 extern void GifDrawText8x8(SavedImage *Image, const int x, const int y,
0275                            const char *legend, const int color);
0276
0277 extern void GifDrawBox(SavedImage *Image, const int x, const int y, const int w,
0278                        const int d, const int color);
0279
0280 extern void GifDrawRectangle(SavedImage *Image, const int x, const int y,
0281                              const int w, const int d, const int color);
0282
0283 extern void GifDrawBoxedText8x8(SavedImage *Image, const int x, const int y,
0284                                 const char *legend, const int border,
0285                                 const int bg, const int fg);
0286
0287 #ifdef __cplusplus
0288 }
0289 #endif /* __cplusplus */
0290 #endif /* _GIF_LIB_H */
0291
0292 /* end */