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.
WebPDemux(const WebPData * data)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.
WebPDemuxPartial(const WebPData * data,WebPDemuxState * state)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_ */
225