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 #ifndef WEBP_WEBP_DEMUX_H_ 48 #define WEBP_WEBP_DEMUX_H_ 49 50 #include "./mux_types.h" 51 52 #if defined(__cplusplus) || defined(c_plusplus) 53 extern "C" { 54 #endif 55 56 #define WEBP_DEMUX_ABI_VERSION 0x0100 // MAJOR(8b) + MINOR(8b) 57 58 // Note: forward declaring enumerations is not allowed in (strict) C and C++, 59 // the types are left here for reference. 60 // typedef enum WebPDemuxState WebPDemuxState; 61 // typedef enum WebPFormatFeature WebPFormatFeature; 62 typedef struct WebPDemuxer WebPDemuxer; 63 typedef struct WebPIterator WebPIterator; 64 typedef struct WebPChunkIterator WebPChunkIterator; 65 66 //------------------------------------------------------------------------------ 67 68 // Returns the version number of the demux library, packed in hexadecimal using 69 // 8bits for each of major/minor/revision. E.g: v2.5.7 is 0x020507. 70 WEBP_EXTERN(int) WebPGetDemuxVersion(void); 71 72 //------------------------------------------------------------------------------ 73 // Life of a Demux object 74 75 typedef enum WebPDemuxState { 76 WEBP_DEMUX_PARSING_HEADER, // Not enough data to parse full header. 77 WEBP_DEMUX_PARSED_HEADER, // Header parsing complete, data may be available. 78 WEBP_DEMUX_DONE // Entire file has been parsed. 79 } WebPDemuxState; 80 81 // Internal, version-checked, entry point 82 WEBP_EXTERN(WebPDemuxer*) WebPDemuxInternal( 83 const WebPData*, int, WebPDemuxState*, int); 84 85 // Parses the full WebP file given by 'data'. 86 // Returns a WebPDemuxer object on successful parse, NULL otherwise. 87 static WEBP_INLINE WebPDemuxer* WebPDemux(const WebPData* data) { 88 return WebPDemuxInternal(data, 0, NULL, WEBP_DEMUX_ABI_VERSION); 89 } 90 91 // Parses the possibly incomplete WebP file given by 'data'. 92 // If 'state' is non-NULL it will be set to indicate the status of the demuxer. 93 // Returns a WebPDemuxer object on successful parse, NULL otherwise. 94 static WEBP_INLINE WebPDemuxer* WebPDemuxPartial( 95 const WebPData* data, WebPDemuxState* state) { 96 return WebPDemuxInternal(data, 1, state, WEBP_DEMUX_ABI_VERSION); 97 } 98 99 // Frees memory associated with 'dmux'. 100 WEBP_EXTERN(void) WebPDemuxDelete(WebPDemuxer* dmux); 101 102 //------------------------------------------------------------------------------ 103 // Data/information extraction. 104 105 typedef enum WebPFormatFeature { 106 WEBP_FF_FORMAT_FLAGS, // Extended format flags present in the 'VP8X' chunk. 107 WEBP_FF_CANVAS_WIDTH, 108 WEBP_FF_CANVAS_HEIGHT, 109 WEBP_FF_LOOP_COUNT, 110 WEBP_FF_BACKGROUND_COLOR, 111 WEBP_FF_FRAME_COUNT // Number of frames present in the demux object. 112 // In case of a partial demux, this is the number of 113 // frames seen so far, with the last frame possibly 114 // being partial. 115 } WebPFormatFeature; 116 117 // Get the 'feature' value from the 'dmux'. 118 // NOTE: values are only valid if WebPDemux() was used or WebPDemuxPartial() 119 // returned a state > WEBP_DEMUX_PARSING_HEADER. 120 WEBP_EXTERN(uint32_t) WebPDemuxGetI( 121 const WebPDemuxer* dmux, WebPFormatFeature feature); 122 123 //------------------------------------------------------------------------------ 124 // Frame iteration. 125 126 struct WebPIterator { 127 int frame_num; 128 int num_frames; // equivalent to WEBP_FF_FRAME_COUNT. 129 int fragment_num; 130 int num_fragments; 131 int x_offset, y_offset; // offset relative to the canvas. 132 int width, height; // dimensions of this frame or fragment. 133 int duration; // display duration in milliseconds. 134 WebPMuxAnimDispose dispose_method; // dispose method for the frame. 135 int complete; // true if 'fragment' contains a full frame. partial images 136 // may still be decoded with the WebP incremental decoder. 137 WebPData fragment; // The frame or fragment given by 'frame_num' and 138 // 'fragment_num'. 139 140 uint32_t pad[4]; // padding for later use. 141 void* private_; // for internal use only. 142 }; 143 144 // Retrieves frame 'frame_number' from 'dmux'. 145 // 'iter->fragment' points to the first fragment on return from this function. 146 // Individual fragments may be extracted using WebPDemuxSetFragment(). 147 // Setting 'frame_number' equal to 0 will return the last frame of the image. 148 // Returns false if 'dmux' is NULL or frame 'frame_number' is not present. 149 // Call WebPDemuxReleaseIterator() when use of the iterator is complete. 150 // NOTE: 'dmux' must persist for the lifetime of 'iter'. 151 WEBP_EXTERN(int) WebPDemuxGetFrame( 152 const WebPDemuxer* dmux, int frame_number, WebPIterator* iter); 153 154 // Sets 'iter->fragment' to point to the next ('iter->frame_num' + 1) or 155 // previous ('iter->frame_num' - 1) frame. These functions do not loop. 156 // Returns true on success, false otherwise. 157 WEBP_EXTERN(int) WebPDemuxNextFrame(WebPIterator* iter); 158 WEBP_EXTERN(int) WebPDemuxPrevFrame(WebPIterator* iter); 159 160 // Sets 'iter->fragment' to reflect fragment number 'fragment_num'. 161 // Returns true if fragment 'fragment_num' is present, false otherwise. 162 WEBP_EXTERN(int) WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num); 163 164 // Releases any memory associated with 'iter'. 165 // Must be called before any subsequent calls to WebPDemuxGetChunk() on the same 166 // iter. Also, must be called before destroying the associated WebPDemuxer with 167 // WebPDemuxDelete(). 168 WEBP_EXTERN(void) WebPDemuxReleaseIterator(WebPIterator* iter); 169 170 //------------------------------------------------------------------------------ 171 // Chunk iteration. 172 173 struct WebPChunkIterator { 174 // The current and total number of chunks with the fourcc given to 175 // WebPDemuxGetChunk(). 176 int chunk_num; 177 int num_chunks; 178 WebPData chunk; // The payload of the chunk. 179 180 uint32_t pad[6]; // padding for later use 181 void* private_; 182 }; 183 184 // Retrieves the 'chunk_number' instance of the chunk with id 'fourcc' from 185 // 'dmux'. 186 // 'fourcc' is a character array containing the fourcc of the chunk to return, 187 // e.g., "ICCP", "XMP ", "EXIF", etc. 188 // Setting 'chunk_number' equal to 0 will return the last chunk in a set. 189 // Returns true if the chunk is found, false otherwise. Image related chunk 190 // payloads are accessed through WebPDemuxGetFrame() and related functions. 191 // Call WebPDemuxReleaseChunkIterator() when use of the iterator is complete. 192 // NOTE: 'dmux' must persist for the lifetime of the iterator. 193 WEBP_EXTERN(int) WebPDemuxGetChunk(const WebPDemuxer* dmux, 194 const char fourcc[4], int chunk_number, 195 WebPChunkIterator* iter); 196 197 // Sets 'iter->chunk' to point to the next ('iter->chunk_num' + 1) or previous 198 // ('iter->chunk_num' - 1) chunk. These functions do not loop. 199 // Returns true on success, false otherwise. 200 WEBP_EXTERN(int) WebPDemuxNextChunk(WebPChunkIterator* iter); 201 WEBP_EXTERN(int) WebPDemuxPrevChunk(WebPChunkIterator* iter); 202 203 // Releases any memory associated with 'iter'. 204 // Must be called before destroying the associated WebPDemuxer with 205 // WebPDemuxDelete(). 206 WEBP_EXTERN(void) WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter); 207 208 //------------------------------------------------------------------------------ 209 210 #if defined(__cplusplus) || defined(c_plusplus) 211 } // extern "C" 212 #endif 213 214 #endif /* WEBP_WEBP_DEMUX_H_ */ 215
