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
54extern "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;
63typedef struct WebPDemuxer WebPDemuxer;
64typedef struct WebPIterator WebPIterator;
65typedef 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.
71WEBP_EXTERN(int) WebPGetDemuxVersion(void);
72
73//------------------------------------------------------------------------------
74// Life of a Demux object
75
76typedef 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
85WEBP_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.
90static 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.
102static 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'.
108WEBP_EXTERN(void) WebPDemuxDelete(WebPDemuxer* dmux);
109
110//------------------------------------------------------------------------------
111// Data/information extraction.
112
113typedef 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.
128WEBP_EXTERN(uint32_t) WebPDemuxGetI(
129    const WebPDemuxer* dmux, WebPFormatFeature feature);
130
131//------------------------------------------------------------------------------
132// Frame iteration.
133
134struct 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'.
161WEBP_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.
167WEBP_EXTERN(int) WebPDemuxNextFrame(WebPIterator* iter);
168WEBP_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.
172WEBP_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().
178WEBP_EXTERN(void) WebPDemuxReleaseIterator(WebPIterator* iter);
179
180//------------------------------------------------------------------------------
181// Chunk iteration.
182
183struct 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.
203WEBP_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.
210WEBP_EXTERN(int) WebPDemuxNextChunk(WebPChunkIterator* iter);
211WEBP_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().
216WEBP_EXTERN(void) WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);
217
218//------------------------------------------------------------------------------
219
220#ifdef __cplusplus
221}    // extern "C"
222#endif
223
224#endif  /* WEBP_WEBP_DEMUX_H_ */
225