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