third_party/libwebp/webp/demux.h

   1 // Copyright 2012 Google Inc. All Rights Reserved.
   2 //
   3 // Use of this source code is governed by a BSD-style license
   4 // that can be found in the COPYING file in the root of the source
   5 // tree. An additional intellectual property rights grant can be found
   6 // in the file PATENTS. All contributing project authors may
   7 // be found in the AUTHORS file in the root of the source tree.
   8 // -----------------------------------------------------------------------------
   9 //
  10 // Demux API.
  11 // Enables extraction of image and extended format data from WebP files.
  12
  13 // Code Example: Demuxing WebP data to extract all the frames, ICC profile
  14 // and EXIF/XMP metadata.
  15 /*
  16   WebPDemuxer* demux = WebPDemux(&webp_data);
  17
  18   uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
  19   uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
  20   // ... (Get information about the features present in the WebP file).
  21   uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);
  22
  23   // ... (Iterate over all frames).
  24   WebPIterator iter;
  25   if (WebPDemuxGetFrame(demux, 1, &iter)) {
  26     do {
  27       // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
  28       // ... and get other frame properties like width, height, offsets etc.
  29       // ... see 'struct WebPIterator' below for more info).
  30     } while (WebPDemuxNextFrame(&iter));
  31     WebPDemuxReleaseIterator(&iter);
  32   }
  33
  34   // ... (Extract metadata).
  35   WebPChunkIterator chunk_iter;
  36   if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
  37   // ... (Consume the ICC profile in 'chunk_iter.chunk').
  38   WebPDemuxReleaseChunkIterator(&chunk_iter);
  39   if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
  40   // ... (Consume the EXIF metadata in 'chunk_iter.chunk').
  41   WebPDemuxReleaseChunkIterator(&chunk_iter);
  42   if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
  43   // ... (Consume the XMP metadata in 'chunk_iter.chunk').
  44   WebPDemuxReleaseChunkIterator(&chunk_iter);
  45   WebPDemuxDelete(demux);
  46 */
  47
  48 #ifndef WEBP_WEBP_DEMUX_H_
  49 #define WEBP_WEBP_DEMUX_H_
  50
  51 #include "./mux_types.h"
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 #define WEBP_DEMUX_ABI_VERSION 0x0101    // MAJOR(8b) + MINOR(8b)
  58
  59 // Note: forward declaring enumerations is not allowed in (strict) C and C++,
  60 // the types are left here for reference.
  61 // typedef enum WebPDemuxState WebPDemuxState;
  62 // typedef enum WebPFormatFeature WebPFormatFeature;
  63 typedef struct WebPDemuxer WebPDemuxer;
  64 typedef struct WebPIterator WebPIterator;
  65 typedef struct WebPChunkIterator WebPChunkIterator;
  66
  67 //------------------------------------------------------------------------------
  68
  69 // Returns the version number of the demux library, packed in hexadecimal using
  70 // 8bits for each of major/minor/revision. E.g: v2.5.7 is 0x020507.
  71 WEBP_EXTERN(int) WebPGetDemuxVersion(void);
  72
  73 //------------------------------------------------------------------------------
  74 // Life of a Demux object
  75
  76 typedef enum WebPDemuxState {
  77   WEBP_DEMUX_PARSE_ERROR    = -1,  // An error occurred while parsing.
  78   WEBP_DEMUX_PARSING_HEADER =  0,  // Not enough data to parse full header.
  79   WEBP_DEMUX_PARSED_HEADER  =  1,  // Header parsing complete,
  80                                    // data may be available.
  81   WEBP_DEMUX_DONE           =  2   // Entire file has been parsed.
  82 } WebPDemuxState;
  83
  84 // Internal, version-checked, entry point
  85 WEBP_EXTERN(WebPDemuxer*) WebPDemuxInternal(
  86     const WebPData*, int, WebPDemuxState*, int);
  87
  88 // Parses the full WebP file given by 'data'.
  89 // Returns a WebPDemuxer object on successful parse, NULL otherwise.
  90 static WEBP_INLINE WebPDemuxer* WebPDemux(const WebPData* data) {
  91   return WebPDemuxInternal(data, 0, NULL, WEBP_DEMUX_ABI_VERSION);
  92 }
  93
  94 // Parses the possibly incomplete WebP file given by 'data'.
  95 // If 'state' is non-NULL it will be set to indicate the status of the demuxer.
  96 // Returns NULL in case of error or if there isn't enough data to start parsing;
  97 // and a WebPDemuxer object on successful parse.
  98 // Note that WebPDemuxer keeps internal pointers to 'data' memory segment.
  99 // If this data is volatile, the demuxer object should be deleted (by calling
 100 // WebPDemuxDelete()) and WebPDemuxPartial() called again on the new data.
 101 // This is usually an inexpensive operation.
 102 static WEBP_INLINE WebPDemuxer* WebPDemuxPartial(
 103     const WebPData* data, WebPDemuxState* state) {
 104   return WebPDemuxInternal(data, 1, state, WEBP_DEMUX_ABI_VERSION);
 105 }
 106
 107 // Frees memory associated with 'dmux'.
 108 WEBP_EXTERN(void) WebPDemuxDelete(WebPDemuxer* dmux);
 109
 110 //------------------------------------------------------------------------------
 111 // Data/information extraction.
 112
 113 typedef enum WebPFormatFeature {
 114   WEBP_FF_FORMAT_FLAGS,  // Extended format flags present in the 'VP8X' chunk.
 115   WEBP_FF_CANVAS_WIDTH,
 116   WEBP_FF_CANVAS_HEIGHT,
 117   WEBP_FF_LOOP_COUNT,
 118   WEBP_FF_BACKGROUND_COLOR,
 119   WEBP_FF_FRAME_COUNT    // Number of frames present in the demux object.
 120                          // In case of a partial demux, this is the number of
 121                          // frames seen so far, with the last frame possibly
 122                          // being partial.
 123 } WebPFormatFeature;
 124
 125 // Get the 'feature' value from the 'dmux'.
 126 // NOTE: values are only valid if WebPDemux() was used or WebPDemuxPartial()
 127 // returned a state > WEBP_DEMUX_PARSING_HEADER.
 128 WEBP_EXTERN(uint32_t) WebPDemuxGetI(
 129     const WebPDemuxer* dmux, WebPFormatFeature feature);
 130
 131 //------------------------------------------------------------------------------
 132 // Frame iteration.
 133
 134 struct WebPIterator {
 135   int frame_num;
 136   int num_frames;          // equivalent to WEBP_FF_FRAME_COUNT.
 137   int fragment_num;
 138   int num_fragments;
 139   int x_offset, y_offset;  // offset relative to the canvas.
 140   int width, height;       // dimensions of this frame or fragment.
 141   int duration;            // display duration in milliseconds.
 142   WebPMuxAnimDispose dispose_method;  // dispose method for the frame.
 143   int complete;   // true if 'fragment' contains a full frame. partial images
 144                   // may still be decoded with the WebP incremental decoder.
 145   WebPData fragment;  // The frame or fragment given by 'frame_num' and
 146                       // 'fragment_num'.
 147   int has_alpha;      // True if the frame or fragment contains transparency.
 148   WebPMuxAnimBlend blend_method;  // Blend operation for the frame.
 149
 150   uint32_t pad[2];         // padding for later use.
 151   void* private_;          // for internal use only.
 152 };
 153
 154 // Retrieves frame 'frame_number' from 'dmux'.
 155 // 'iter->fragment' points to the first fragment on return from this function.
 156 // Individual fragments may be extracted using WebPDemuxSelectFragment().
 157 // Setting 'frame_number' equal to 0 will return the last frame of the image.
 158 // Returns false if 'dmux' is NULL or frame 'frame_number' is not present.
 159 // Call WebPDemuxReleaseIterator() when use of the iterator is complete.
 160 // NOTE: 'dmux' must persist for the lifetime of 'iter'.
 161 WEBP_EXTERN(int) WebPDemuxGetFrame(
 162     const WebPDemuxer* dmux, int frame_number, WebPIterator* iter);
 163
 164 // Sets 'iter->fragment' to point to the next ('iter->frame_num' + 1) or
 165 // previous ('iter->frame_num' - 1) frame. These functions do not loop.
 166 // Returns true on success, false otherwise.
 167 WEBP_EXTERN(int) WebPDemuxNextFrame(WebPIterator* iter);
 168 WEBP_EXTERN(int) WebPDemuxPrevFrame(WebPIterator* iter);
 169
 170 // Sets 'iter->fragment' to reflect fragment number 'fragment_num'.
 171 // Returns true if fragment 'fragment_num' is present, false otherwise.
 172 WEBP_EXTERN(int) WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);
 173
 174 // Releases any memory associated with 'iter'.
 175 // Must be called before any subsequent calls to WebPDemuxGetChunk() on the same
 176 // iter. Also, must be called before destroying the associated WebPDemuxer with
 177 // WebPDemuxDelete().
 178 WEBP_EXTERN(void) WebPDemuxReleaseIterator(WebPIterator* iter);
 179
 180 //------------------------------------------------------------------------------
 181 // Chunk iteration.
 182
 183 struct WebPChunkIterator {
 184   // The current and total number of chunks with the fourcc given to
 185   // WebPDemuxGetChunk().
 186   int chunk_num;
 187   int num_chunks;
 188   WebPData chunk;    // The payload of the chunk.
 189
 190   uint32_t pad[6];   // padding for later use
 191   void* private_;
 192 };
 193
 194 // Retrieves the 'chunk_number' instance of the chunk with id 'fourcc' from
 195 // 'dmux'.
 196 // 'fourcc' is a character array containing the fourcc of the chunk to return,
 197 // e.g., "ICCP", "XMP ", "EXIF", etc.
 198 // Setting 'chunk_number' equal to 0 will return the last chunk in a set.
 199 // Returns true if the chunk is found, false otherwise. Image related chunk
 200 // payloads are accessed through WebPDemuxGetFrame() and related functions.
 201 // Call WebPDemuxReleaseChunkIterator() when use of the iterator is complete.
 202 // NOTE: 'dmux' must persist for the lifetime of the iterator.
 203 WEBP_EXTERN(int) WebPDemuxGetChunk(const WebPDemuxer* dmux,
 204                                    const char fourcc[4], int chunk_number,
 205                                    WebPChunkIterator* iter);
 206
 207 // Sets 'iter->chunk' to point to the next ('iter->chunk_num' + 1) or previous
 208 // ('iter->chunk_num' - 1) chunk. These functions do not loop.
 209 // Returns true on success, false otherwise.
 210 WEBP_EXTERN(int) WebPDemuxNextChunk(WebPChunkIterator* iter);
 211 WEBP_EXTERN(int) WebPDemuxPrevChunk(WebPChunkIterator* iter);
 212
 213 // Releases any memory associated with 'iter'.
 214 // Must be called before destroying the associated WebPDemuxer with
 215 // WebPDemuxDelete().
 216 WEBP_EXTERN(void) WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);
 217
 218 //------------------------------------------------------------------------------
 219
 220 #ifdef __cplusplus
 221 }    // extern "C"
 222 #endif
 223
 224 #endif  /* WEBP_WEBP_DEMUX_H_ */