General API - dloebl/cgif GitHub Wiki

Functions

cgif_newgif()

Description

Creates new GIF output stream with the config provided (pConfig).

Parameters

1. pConfig:CGIF_Config*: Pointer to the configuration for the new GIF to be created; can be changed after cgif_newgif() returns - CGIF keeps an internal copy.

Return value

Returns pointer to new CGIF instance or NULL on error.

cgif_addframe()

Description

Adds new frame sequentially to the given open GIF stream.

Parameters

  1. pGIF:CGIF*: GIF handle (priorly created with cgif_newgif)
  2. pConfig:CGIF_FrameConfig*: Pointer to the configuration for the new frame to be added; can be changed after cgif_addframe() returns - CGIF keeps an internal copy.

Return value

Returns CGIF_OK on success or an error code.

cgif_close()

Description

Closes the given GIF stream. If a previous call to cgif_addframe failed, the previous error code will be returned.

Parameters

  1. pGIF:CGIF*: GIF handle (priorly created with cgif_newgif)

Return value

Returns CGIF_OK on success or an error code.

Types

CGIF_Config

  1. pGlobalPalette:uint8_t*: Global palette of GIF. Size MUST be a multiple of 3 (r,g,b format) if CGIF_ATTR_NO_GLOBAL_TABLE is not set.
  2. path:const char*: NUL terminated path to the new GIF to be created (mutually exclusive with pWriteFn).
  3. attrFlags:uint32_t: Fixed attributes of the GIF (see section Flags)
  4. genFlags:uint32_t: Flags that determine how the GIF is generated.
  5. width:uint16_t: Width (in pixels) of the complete graphic
  6. height:uint16_t: Height (in pixels) of the complete graphic
  7. numGlobalPaletteEntries:uint16_t: Number of palette entries provided with pGlobalPalette. MUST be >= 1 if CGIF_ATTR_NO_GLOBAL_TABLE is not set.
  8. numLoops:uint16_t: Number of repetitions to perform for an animated GIF (NETSCAPE2.0 extension). Only evaluated if CGIF_ATTR_IS_ANIMATED is set.
  9. pWriteFn:cgif_write_fn* Callback function to stream GIF (mutually exclusive with path).
  10. pContext:void*: Opaque pointer passed as the first parameter to pWriteFn.

CGIF_FrameConfig

  1. pLocalPalette:uint8_t*: Local palette of Frame. Size MUST be a multiple of 3 (r,g,b format) if GIF_FRAME_ATTR_USE_LOCAL_TABLE set.
  2. pImageData:uint8_t*: Image data to be encoded. One byte per pixel (reference to palette).
  3. attrFlags:uint32_t: Fixed attributes of the Frame (see Flags).
  4. genFlags:uint32_t: Flags that determine how the Frame is generated.
  5. delay:uint16_t: delay before the next frame is shown (units of 0.01s). Only evaluated if GIF_ATTR_IS_ANIMATED is set.
  6. numLocalPaletteEntries:uint16_t: Number of palette entries provided with pLocalPalette. MUST be >= 1 if CGIF_FRAME_ATTR_USE_LOCAL_TABLE is set.
  7. transIndex:uint8_t: Transparency index. Only used when either CGIF_FRAME_ATTR_HAS_SET_TRANS or CGIF_FRAME_ATTR_HAS_ALPHA is set.

Flags

  • CGIF_ATTR_IS_ANIMATED: Make an animated GIF (default is non-animated GIF).
  • CGIF_ATTR_NO_GLOBAL_TABLE: Disable global color table (global color table is default)
  • CGIF_ATTR_HAS_TRANSPARENCY: First entry in all color tables (index: 0) contains transparency (alpha channel)
  • CGIF_FRAME_ATTR_USE_LOCAL_TABLE: Use a local color table for a frame (local color table is not used by default)
  • CGIF_FRAME_ATTR_HAS_ALPHA: Frame contains transparency/alpha channel (index set via transIndex field)
  • CGIF_FRAME_ATTR_HAS_SET_TRANS: Transparency setting (which pixels are identical to previos frame) provided by user (transIndex field)
  • CGIF_FRAME_GEN_USE_TRANSPARENCY: Use transparency optimization (set pixels that are identical to previous frame to transparent - might decrease size)
  • CGIF_FRAME_GEN_USE_DIFF_WINDOW: Do encoding just for the sub-window that has changed from the previous frame (decreases size)

Result codes

  • CGIF_OK: everything OK. The GIF stream is still valid.
  • CGIF_EWRITE: writing GIF data failed (via fwrite() or callback).
  • CGIF_EALLOC: allocating memory failed.
  • CGIF_ECLOSE: final call to fclose failed
  • CGIF_EOPEN: failed to open output file.
  • CGIF_EINDEX: user provided invalid index in image data.
  • CGIF_ERROR: something unspecified failed.