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 "./decode.h" // for WEBP_CSP_MODE 
52#include "./mux_types.h" 
53 
54#ifdef __cplusplus 
55extern "C" { 
56#endif 
57 
58#define WEBP_DEMUX_ABI_VERSION 0x0107 // MAJOR(8b) + MINOR(8b) 
59 
60// Note: forward declaring enumerations is not allowed in (strict) C and C++, 
61// the types are left here for reference. 
62// typedef enum WebPDemuxState WebPDemuxState; 
63// typedef enum WebPFormatFeature WebPFormatFeature; 
64typedef struct WebPDemuxer WebPDemuxer; 
65typedef struct WebPIterator WebPIterator; 
66typedef struct WebPChunkIterator WebPChunkIterator; 
67typedef struct WebPAnimInfo WebPAnimInfo; 
68typedef struct WebPAnimDecoderOptions WebPAnimDecoderOptions; 
69 
70//------------------------------------------------------------------------------ 
71 
72// Returns the version number of the demux library, packed in hexadecimal using 
73// 8bits for each of major/minor/revision. E.g: v2.5.7 is 0x020507. 
74WEBP_EXTERN int WebPGetDemuxVersion(void); 
75 
76//------------------------------------------------------------------------------ 
77// Life of a Demux object 
78 
79typedef enum WebPDemuxState { 
80 WEBP_DEMUX_PARSE_ERROR = -1, // An error occurred while parsing. 
81 WEBP_DEMUX_PARSING_HEADER = 0, // Not enough data to parse full header. 
82 WEBP_DEMUX_PARSED_HEADER = 1, // Header parsing complete, 
83 // data may be available. 
84 WEBP_DEMUX_DONE = 2 // Entire file has been parsed. 
85} WebPDemuxState; 
86 
87// Internal, version-checked, entry point 
88WEBP_EXTERN WebPDemuxer* WebPDemuxInternal( 
89 const WebPData*, int, WebPDemuxState*, int); 
90 
91// Parses the full WebP file given by 'data'. For single images the WebP file 
92// header alone or the file header and the chunk header may be absent. 
93// Returns a WebPDemuxer object on successful parse, NULL otherwise. 
94static WEBP_INLINE WebPDemuxer* WebPDemux(const WebPData* data) { 
95 return WebPDemuxInternal(data, 0, NULL, WEBP_DEMUX_ABI_VERSION); 
96} 
97 
98// Parses the possibly incomplete WebP file given by 'data'. 
99// If 'state' is non-NULL it will be set to indicate the status of the demuxer. 
100// Returns NULL in case of error or if there isn't enough data to start parsing; 
101// and a WebPDemuxer object on successful parse. 
102// Note that WebPDemuxer keeps internal pointers to 'data' memory segment. 
103// If this data is volatile, the demuxer object should be deleted (by calling 
104// WebPDemuxDelete()) and WebPDemuxPartial() called again on the new data. 
105// This is usually an inexpensive operation. 
106static WEBP_INLINE WebPDemuxer* WebPDemuxPartial( 
107 const WebPData* data, WebPDemuxState* state) { 
108 return WebPDemuxInternal(data, 1, state, WEBP_DEMUX_ABI_VERSION); 
109} 
110 
111// Frees memory associated with 'dmux'. 
112WEBP_EXTERN void WebPDemuxDelete(WebPDemuxer* dmux); 
113 
114//------------------------------------------------------------------------------ 
115// Data/information extraction. 
116 
117typedef enum WebPFormatFeature { 
118 WEBP_FF_FORMAT_FLAGS, // bit-wise combination of WebPFeatureFlags 
119 // corresponding to the 'VP8X' chunk (if present). 
120 WEBP_FF_CANVAS_WIDTH, 
121 WEBP_FF_CANVAS_HEIGHT, 
122 WEBP_FF_LOOP_COUNT, // only relevant for animated file 
123 WEBP_FF_BACKGROUND_COLOR, // idem. 
124 WEBP_FF_FRAME_COUNT // Number of frames present in the demux object. 
125 // In case of a partial demux, this is the number 
126 // of frames seen so far, with the last frame 
127 // possibly being partial. 
128} WebPFormatFeature; 
129 
130// Get the 'feature' value from the 'dmux'. 
131// NOTE: values are only valid if WebPDemux() was used or WebPDemuxPartial() 
132// returned a state > WEBP_DEMUX_PARSING_HEADER. 
133// If 'feature' is WEBP_FF_FORMAT_FLAGS, the returned value is a bit-wise 
134// combination of WebPFeatureFlags values. 
135// If 'feature' is WEBP_FF_LOOP_COUNT, WEBP_FF_BACKGROUND_COLOR, the returned 
136// value is only meaningful if the bitstream is animated. 
137WEBP_EXTERN uint32_t WebPDemuxGetI( 
138 const WebPDemuxer* dmux, WebPFormatFeature feature); 
139 
140//------------------------------------------------------------------------------ 
141// Frame iteration. 
142 
143struct WebPIterator { 
144 int frame_num; 
145 int num_frames; // equivalent to WEBP_FF_FRAME_COUNT. 
146 int x_offset, y_offset; // offset relative to the canvas. 
147 int width, height; // dimensions of this frame. 
148 int duration; // display duration in milliseconds. 
149 WebPMuxAnimDispose dispose_method; // dispose method for the frame. 
150 int complete; // true if 'fragment' contains a full frame. partial images 
151 // may still be decoded with the WebP incremental decoder. 
152 WebPData fragment; // The frame given by 'frame_num'. Note for historical 
153 // reasons this is called a fragment. 
154 int has_alpha; // True if the frame contains transparency. 
155 WebPMuxAnimBlend blend_method; // Blend operation for the frame. 
156 
157 uint32_t pad[2]; // padding for later use. 
158 void* private_; // for internal use only. 
159}; 
160 
161// Retrieves frame 'frame_number' from 'dmux'. 
162// 'iter->fragment' points to the frame on return from this function. 
163// Setting 'frame_number' equal to 0 will return the last frame of the image. 
164// Returns false if 'dmux' is NULL or frame 'frame_number' is not present. 
165// Call WebPDemuxReleaseIterator() when use of the iterator is complete. 
166// NOTE: 'dmux' must persist for the lifetime of 'iter'. 
167WEBP_EXTERN int WebPDemuxGetFrame( 
168 const WebPDemuxer* dmux, int frame_number, WebPIterator* iter); 
169 
170// Sets 'iter->fragment' to point to the next ('iter->frame_num' + 1) or 
171// previous ('iter->frame_num' - 1) frame. These functions do not loop. 
172// Returns true on success, false otherwise. 
173WEBP_EXTERN int WebPDemuxNextFrame(WebPIterator* iter); 
174WEBP_EXTERN int WebPDemuxPrevFrame(WebPIterator* iter); 
175 
176// Releases any memory associated with 'iter'. 
177// Must be called before any subsequent calls to WebPDemuxGetChunk() on the same 
178// iter. Also, must be called before destroying the associated WebPDemuxer with 
179// WebPDemuxDelete(). 
180WEBP_EXTERN void WebPDemuxReleaseIterator(WebPIterator* iter); 
181 
182//------------------------------------------------------------------------------ 
183// Chunk iteration. 
184 
185struct WebPChunkIterator { 
186 // The current and total number of chunks with the fourcc given to 
187 // WebPDemuxGetChunk(). 
188 int chunk_num; 
189 int num_chunks; 
190 WebPData chunk; // The payload of the chunk. 
191 
192 uint32_t pad[6]; // padding for later use 
193 void* private_; 
194}; 
195 
196// Retrieves the 'chunk_number' instance of the chunk with id 'fourcc' from 
197// 'dmux'. 
198// 'fourcc' is a character array containing the fourcc of the chunk to return, 
199// e.g., "ICCP", "XMP ", "EXIF", etc. 
200// Setting 'chunk_number' equal to 0 will return the last chunk in a set. 
201// Returns true if the chunk is found, false otherwise. Image related chunk 
202// payloads are accessed through WebPDemuxGetFrame() and related functions. 
203// Call WebPDemuxReleaseChunkIterator() when use of the iterator is complete. 
204// NOTE: 'dmux' must persist for the lifetime of the iterator. 
205WEBP_EXTERN int WebPDemuxGetChunk(const WebPDemuxer* dmux, 
206 const char fourcc[4], int chunk_number, 
207 WebPChunkIterator* iter); 
208 
209// Sets 'iter->chunk' to point to the next ('iter->chunk_num' + 1) or previous 
210// ('iter->chunk_num' - 1) chunk. These functions do not loop. 
211// Returns true on success, false otherwise. 
212WEBP_EXTERN int WebPDemuxNextChunk(WebPChunkIterator* iter); 
213WEBP_EXTERN int WebPDemuxPrevChunk(WebPChunkIterator* iter); 
214 
215// Releases any memory associated with 'iter'. 
216// Must be called before destroying the associated WebPDemuxer with 
217// WebPDemuxDelete(). 
218WEBP_EXTERN void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter); 
219 
220//------------------------------------------------------------------------------ 
221// WebPAnimDecoder API 
222// 
223// This API allows decoding (possibly) animated WebP images. 
224// 
225// Code Example: 
226/* 
227 WebPAnimDecoderOptions dec_options; 
228 WebPAnimDecoderOptionsInit(&dec_options); 
229 // Tune 'dec_options' as needed. 
230 WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options); 
231 WebPAnimInfo anim_info; 
232 WebPAnimDecoderGetInfo(dec, &anim_info); 
233 for (uint32_t i = 0; i < anim_info.loop_count; ++i) { 
234 while (WebPAnimDecoderHasMoreFrames(dec)) { 
235 uint8_t* buf; 
236 int timestamp; 
237 WebPAnimDecoderGetNext(dec, &buf, &timestamp); 
238 // ... (Render 'buf' based on 'timestamp'). 
239 // ... (Do NOT free 'buf', as it is owned by 'dec'). 
240 } 
241 WebPAnimDecoderReset(dec); 
242 } 
243 const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec); 
244 // ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data). 
245 WebPAnimDecoderDelete(dec); 
246*/ 
247 
248typedef struct WebPAnimDecoder WebPAnimDecoder; // Main opaque object. 
249 
250// Global options. 
251struct WebPAnimDecoderOptions { 
252 // Output colorspace. Only the following modes are supported: 
253 // MODE_RGBA, MODE_BGRA, MODE_rgbA and MODE_bgrA. 
254 WEBP_CSP_MODE color_mode; 
255 int use_threads; // If true, use multi-threaded decoding. 
256 uint32_t padding[7]; // Padding for later use. 
257}; 
258 
259// Internal, version-checked, entry point. 
260WEBP_EXTERN int WebPAnimDecoderOptionsInitInternal( 
261 WebPAnimDecoderOptions*, int); 
262 
263// Should always be called, to initialize a fresh WebPAnimDecoderOptions 
264// structure before modification. Returns false in case of version mismatch. 
265// WebPAnimDecoderOptionsInit() must have succeeded before using the 
266// 'dec_options' object. 
267static WEBP_INLINE int WebPAnimDecoderOptionsInit( 
268 WebPAnimDecoderOptions* dec_options) { 
269 return WebPAnimDecoderOptionsInitInternal(dec_options, 
270 WEBP_DEMUX_ABI_VERSION); 
271} 
272 
273// Internal, version-checked, entry point. 
274WEBP_EXTERN WebPAnimDecoder* WebPAnimDecoderNewInternal( 
275 const WebPData*, const WebPAnimDecoderOptions*, int); 
276 
277// Creates and initializes a WebPAnimDecoder object. 
278// Parameters: 
279// webp_data - (in) WebP bitstream. This should remain unchanged during the 
280// lifetime of the output WebPAnimDecoder object. 
281// dec_options - (in) decoding options. Can be passed NULL to choose 
282// reasonable defaults (in particular, color mode MODE_RGBA 
283// will be picked). 
284// Returns: 
285// A pointer to the newly created WebPAnimDecoder object, or NULL in case of 
286// parsing error, invalid option or memory error. 
287static WEBP_INLINE WebPAnimDecoder* WebPAnimDecoderNew( 
288 const WebPData* webp_data, const WebPAnimDecoderOptions* dec_options) { 
289 return WebPAnimDecoderNewInternal(webp_data, dec_options, 
290 WEBP_DEMUX_ABI_VERSION); 
291} 
292 
293// Global information about the animation.. 
294struct WebPAnimInfo { 
295 uint32_t canvas_width; 
296 uint32_t canvas_height; 
297 uint32_t loop_count; 
298 uint32_t bgcolor; 
299 uint32_t frame_count; 
300 uint32_t pad[4]; // padding for later use 
301}; 
302 
303// Get global information about the animation. 
304// Parameters: 
305// dec - (in) decoder instance to get information from. 
306// info - (out) global information fetched from the animation. 
307// Returns: 
308// True on success. 
309WEBP_EXTERN int WebPAnimDecoderGetInfo(const WebPAnimDecoder* dec, 
310 WebPAnimInfo* info); 
311 
312// Fetch the next frame from 'dec' based on options supplied to 
313// WebPAnimDecoderNew(). This will be a fully reconstructed canvas of size 
314// 'canvas_width * 4 * canvas_height', and not just the frame sub-rectangle. The 
315// returned buffer 'buf' is valid only until the next call to 
316// WebPAnimDecoderGetNext(), WebPAnimDecoderReset() or WebPAnimDecoderDelete(). 
317// Parameters: 
318// dec - (in/out) decoder instance from which the next frame is to be fetched. 
319// buf - (out) decoded frame. 
320// timestamp - (out) timestamp of the frame in milliseconds. 
321// Returns: 
322// False if any of the arguments are NULL, or if there is a parsing or 
323// decoding error, or if there are no more frames. Otherwise, returns true. 
324WEBP_EXTERN int WebPAnimDecoderGetNext(WebPAnimDecoder* dec, 
325 uint8_t** buf, int* timestamp); 
326 
327// Check if there are more frames left to decode. 
328// Parameters: 
329// dec - (in) decoder instance to be checked. 
330// Returns: 
331// True if 'dec' is not NULL and some frames are yet to be decoded. 
332// Otherwise, returns false. 
333WEBP_EXTERN int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec); 
334 
335// Resets the WebPAnimDecoder object, so that next call to 
336// WebPAnimDecoderGetNext() will restart decoding from 1st frame. This would be 
337// helpful when all frames need to be decoded multiple times (e.g. 
338// info.loop_count times) without destroying and recreating the 'dec' object. 
339// Parameters: 
340// dec - (in/out) decoder instance to be reset 
341WEBP_EXTERN void WebPAnimDecoderReset(WebPAnimDecoder* dec); 
342 
343// Grab the internal demuxer object. 
344// Getting the demuxer object can be useful if one wants to use operations only 
345// available through demuxer; e.g. to get XMP/EXIF/ICC metadata. The returned 
346// demuxer object is owned by 'dec' and is valid only until the next call to 
347// WebPAnimDecoderDelete(). 
348// 
349// Parameters: 
350// dec - (in) decoder instance from which the demuxer object is to be fetched. 
351WEBP_EXTERN const WebPDemuxer* WebPAnimDecoderGetDemuxer( 
352 const WebPAnimDecoder* dec); 
353 
354// Deletes the WebPAnimDecoder object. 
355// Parameters: 
356// dec - (in/out) decoder instance to be deleted 
357WEBP_EXTERN void WebPAnimDecoderDelete(WebPAnimDecoder* dec); 
358 
359#ifdef __cplusplus 
360} // extern "C" 
361#endif 
362 
363#endif // WEBP_WEBP_DEMUX_H_ 
364