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 55 extern "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; 64 typedef struct WebPDemuxer WebPDemuxer; 65 typedef struct WebPIterator WebPIterator; 66 typedef struct WebPChunkIterator WebPChunkIterator; 67 typedef struct WebPAnimInfo WebPAnimInfo; 68 typedef 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. 74 WEBP_EXTERN int WebPGetDemuxVersion(void); 75 76 //------------------------------------------------------------------------------ 77 // Life of a Demux object 78 79 typedef 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 88 WEBP_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. 94 static 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. 106 static 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'. 112 WEBP_EXTERN void WebPDemuxDelete(WebPDemuxer* dmux); 113 114 //------------------------------------------------------------------------------ 115 // Data/information extraction. 116 117 typedef 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. 137 WEBP_EXTERN uint32_t WebPDemuxGetI( 138 const WebPDemuxer* dmux, WebPFormatFeature feature); 139 140 //------------------------------------------------------------------------------ 141 // Frame iteration. 142 143 struct 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'. 167 WEBP_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. 173 WEBP_EXTERN int WebPDemuxNextFrame(WebPIterator* iter); 174 WEBP_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(). 180 WEBP_EXTERN void WebPDemuxReleaseIterator(WebPIterator* iter); 181 182 //------------------------------------------------------------------------------ 183 // Chunk iteration. 184 185 struct 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. 205 WEBP_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. 212 WEBP_EXTERN int WebPDemuxNextChunk(WebPChunkIterator* iter); 213 WEBP_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(). 218 WEBP_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, ×tamp); 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 248 typedef struct WebPAnimDecoder WebPAnimDecoder; // Main opaque object. 249 250 // Global options. 251 struct 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. 260 WEBP_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. 267 static 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. 274 WEBP_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. 287 static 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.. 294 struct 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. 309 WEBP_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. 324 WEBP_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. 333 WEBP_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 341 WEBP_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. 351 WEBP_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 357 WEBP_EXTERN void WebPAnimDecoderDelete(WebPAnimDecoder* dec); 358 359 #ifdef __cplusplus 360 } // extern "C" 361 #endif 362 363 #endif /* WEBP_WEBP_DEMUX_H_ */ 364