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