jpayne@69: // Copyright 2012 Google Inc. All Rights Reserved. jpayne@69: // jpayne@69: // Use of this source code is governed by a BSD-style license jpayne@69: // that can be found in the COPYING file in the root of the source jpayne@69: // tree. An additional intellectual property rights grant can be found jpayne@69: // in the file PATENTS. All contributing project authors may jpayne@69: // be found in the AUTHORS file in the root of the source tree. jpayne@69: // ----------------------------------------------------------------------------- jpayne@69: // jpayne@69: // Demux API. jpayne@69: // Enables extraction of image and extended format data from WebP files. jpayne@69: jpayne@69: // Code Example: Demuxing WebP data to extract all the frames, ICC profile jpayne@69: // and EXIF/XMP metadata. jpayne@69: /* jpayne@69: WebPDemuxer* demux = WebPDemux(&webp_data); jpayne@69: jpayne@69: uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH); jpayne@69: uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT); jpayne@69: // ... (Get information about the features present in the WebP file). jpayne@69: uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS); jpayne@69: jpayne@69: // ... (Iterate over all frames). jpayne@69: WebPIterator iter; jpayne@69: if (WebPDemuxGetFrame(demux, 1, &iter)) { jpayne@69: do { jpayne@69: // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(), jpayne@69: // ... and get other frame properties like width, height, offsets etc. jpayne@69: // ... see 'struct WebPIterator' below for more info). jpayne@69: } while (WebPDemuxNextFrame(&iter)); jpayne@69: WebPDemuxReleaseIterator(&iter); jpayne@69: } jpayne@69: jpayne@69: // ... (Extract metadata). jpayne@69: WebPChunkIterator chunk_iter; jpayne@69: if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter); jpayne@69: // ... (Consume the ICC profile in 'chunk_iter.chunk'). jpayne@69: WebPDemuxReleaseChunkIterator(&chunk_iter); jpayne@69: if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter); jpayne@69: // ... (Consume the EXIF metadata in 'chunk_iter.chunk'). jpayne@69: WebPDemuxReleaseChunkIterator(&chunk_iter); jpayne@69: if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter); jpayne@69: // ... (Consume the XMP metadata in 'chunk_iter.chunk'). jpayne@69: WebPDemuxReleaseChunkIterator(&chunk_iter); jpayne@69: WebPDemuxDelete(demux); jpayne@69: */ jpayne@69: jpayne@69: #ifndef WEBP_WEBP_DEMUX_H_ jpayne@69: #define WEBP_WEBP_DEMUX_H_ jpayne@69: jpayne@69: #include "./decode.h" // for WEBP_CSP_MODE jpayne@69: #include "./mux_types.h" jpayne@69: #include "./types.h" jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: extern "C" { jpayne@69: #endif jpayne@69: jpayne@69: #define WEBP_DEMUX_ABI_VERSION 0x0107 // MAJOR(8b) + MINOR(8b) jpayne@69: jpayne@69: // Note: forward declaring enumerations is not allowed in (strict) C and C++, jpayne@69: // the types are left here for reference. jpayne@69: // typedef enum WebPDemuxState WebPDemuxState; jpayne@69: // typedef enum WebPFormatFeature WebPFormatFeature; jpayne@69: typedef struct WebPDemuxer WebPDemuxer; jpayne@69: typedef struct WebPIterator WebPIterator; jpayne@69: typedef struct WebPChunkIterator WebPChunkIterator; jpayne@69: typedef struct WebPAnimInfo WebPAnimInfo; jpayne@69: typedef struct WebPAnimDecoderOptions WebPAnimDecoderOptions; jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: jpayne@69: // Returns the version number of the demux library, packed in hexadecimal using jpayne@69: // 8bits for each of major/minor/revision. E.g: v2.5.7 is 0x020507. jpayne@69: WEBP_EXTERN int WebPGetDemuxVersion(void); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Life of a Demux object jpayne@69: jpayne@69: typedef enum WebPDemuxState { jpayne@69: WEBP_DEMUX_PARSE_ERROR = -1, // An error occurred while parsing. jpayne@69: WEBP_DEMUX_PARSING_HEADER = 0, // Not enough data to parse full header. jpayne@69: WEBP_DEMUX_PARSED_HEADER = 1, // Header parsing complete, jpayne@69: // data may be available. jpayne@69: WEBP_DEMUX_DONE = 2 // Entire file has been parsed. jpayne@69: } WebPDemuxState; jpayne@69: jpayne@69: // Internal, version-checked, entry point jpayne@69: WEBP_NODISCARD WEBP_EXTERN WebPDemuxer* WebPDemuxInternal( jpayne@69: const WebPData*, int, WebPDemuxState*, int); jpayne@69: jpayne@69: // Parses the full WebP file given by 'data'. For single images the WebP file jpayne@69: // header alone or the file header and the chunk header may be absent. jpayne@69: // Returns a WebPDemuxer object on successful parse, NULL otherwise. jpayne@69: WEBP_NODISCARD static WEBP_INLINE WebPDemuxer* WebPDemux(const WebPData* data) { jpayne@69: return WebPDemuxInternal(data, 0, NULL, WEBP_DEMUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: // Parses the possibly incomplete WebP file given by 'data'. jpayne@69: // If 'state' is non-NULL it will be set to indicate the status of the demuxer. jpayne@69: // Returns NULL in case of error or if there isn't enough data to start parsing; jpayne@69: // and a WebPDemuxer object on successful parse. jpayne@69: // Note that WebPDemuxer keeps internal pointers to 'data' memory segment. jpayne@69: // If this data is volatile, the demuxer object should be deleted (by calling jpayne@69: // WebPDemuxDelete()) and WebPDemuxPartial() called again on the new data. jpayne@69: // This is usually an inexpensive operation. jpayne@69: WEBP_NODISCARD static WEBP_INLINE WebPDemuxer* WebPDemuxPartial( jpayne@69: const WebPData* data, WebPDemuxState* state) { jpayne@69: return WebPDemuxInternal(data, 1, state, WEBP_DEMUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: // Frees memory associated with 'dmux'. jpayne@69: WEBP_EXTERN void WebPDemuxDelete(WebPDemuxer* dmux); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Data/information extraction. jpayne@69: jpayne@69: typedef enum WebPFormatFeature { jpayne@69: WEBP_FF_FORMAT_FLAGS, // bit-wise combination of WebPFeatureFlags jpayne@69: // corresponding to the 'VP8X' chunk (if present). jpayne@69: WEBP_FF_CANVAS_WIDTH, jpayne@69: WEBP_FF_CANVAS_HEIGHT, jpayne@69: WEBP_FF_LOOP_COUNT, // only relevant for animated file jpayne@69: WEBP_FF_BACKGROUND_COLOR, // idem. jpayne@69: WEBP_FF_FRAME_COUNT // Number of frames present in the demux object. jpayne@69: // In case of a partial demux, this is the number jpayne@69: // of frames seen so far, with the last frame jpayne@69: // possibly being partial. jpayne@69: } WebPFormatFeature; jpayne@69: jpayne@69: // Get the 'feature' value from the 'dmux'. jpayne@69: // NOTE: values are only valid if WebPDemux() was used or WebPDemuxPartial() jpayne@69: // returned a state > WEBP_DEMUX_PARSING_HEADER. jpayne@69: // If 'feature' is WEBP_FF_FORMAT_FLAGS, the returned value is a bit-wise jpayne@69: // combination of WebPFeatureFlags values. jpayne@69: // If 'feature' is WEBP_FF_LOOP_COUNT, WEBP_FF_BACKGROUND_COLOR, the returned jpayne@69: // value is only meaningful if the bitstream is animated. jpayne@69: WEBP_EXTERN uint32_t WebPDemuxGetI( jpayne@69: const WebPDemuxer* dmux, WebPFormatFeature feature); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Frame iteration. jpayne@69: jpayne@69: struct WebPIterator { jpayne@69: int frame_num; jpayne@69: int num_frames; // equivalent to WEBP_FF_FRAME_COUNT. jpayne@69: int x_offset, y_offset; // offset relative to the canvas. jpayne@69: int width, height; // dimensions of this frame. jpayne@69: int duration; // display duration in milliseconds. jpayne@69: WebPMuxAnimDispose dispose_method; // dispose method for the frame. jpayne@69: int complete; // true if 'fragment' contains a full frame. partial images jpayne@69: // may still be decoded with the WebP incremental decoder. jpayne@69: WebPData fragment; // The frame given by 'frame_num'. Note for historical jpayne@69: // reasons this is called a fragment. jpayne@69: int has_alpha; // True if the frame contains transparency. jpayne@69: WebPMuxAnimBlend blend_method; // Blend operation for the frame. jpayne@69: jpayne@69: uint32_t pad[2]; // padding for later use. jpayne@69: void* private_; // for internal use only. jpayne@69: }; jpayne@69: jpayne@69: // Retrieves frame 'frame_number' from 'dmux'. jpayne@69: // 'iter->fragment' points to the frame on return from this function. jpayne@69: // Setting 'frame_number' equal to 0 will return the last frame of the image. jpayne@69: // Returns false if 'dmux' is NULL or frame 'frame_number' is not present. jpayne@69: // Call WebPDemuxReleaseIterator() when use of the iterator is complete. jpayne@69: // NOTE: 'dmux' must persist for the lifetime of 'iter'. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPDemuxGetFrame( jpayne@69: const WebPDemuxer* dmux, int frame_number, WebPIterator* iter); jpayne@69: jpayne@69: // Sets 'iter->fragment' to point to the next ('iter->frame_num' + 1) or jpayne@69: // previous ('iter->frame_num' - 1) frame. These functions do not loop. jpayne@69: // Returns true on success, false otherwise. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPDemuxNextFrame(WebPIterator* iter); jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPDemuxPrevFrame(WebPIterator* iter); jpayne@69: jpayne@69: // Releases any memory associated with 'iter'. jpayne@69: // Must be called before any subsequent calls to WebPDemuxGetChunk() on the same jpayne@69: // iter. Also, must be called before destroying the associated WebPDemuxer with jpayne@69: // WebPDemuxDelete(). jpayne@69: WEBP_EXTERN void WebPDemuxReleaseIterator(WebPIterator* iter); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Chunk iteration. jpayne@69: jpayne@69: struct WebPChunkIterator { jpayne@69: // The current and total number of chunks with the fourcc given to jpayne@69: // WebPDemuxGetChunk(). jpayne@69: int chunk_num; jpayne@69: int num_chunks; jpayne@69: WebPData chunk; // The payload of the chunk. jpayne@69: jpayne@69: uint32_t pad[6]; // padding for later use jpayne@69: void* private_; jpayne@69: }; jpayne@69: jpayne@69: // Retrieves the 'chunk_number' instance of the chunk with id 'fourcc' from jpayne@69: // 'dmux'. jpayne@69: // 'fourcc' is a character array containing the fourcc of the chunk to return, jpayne@69: // e.g., "ICCP", "XMP ", "EXIF", etc. jpayne@69: // Setting 'chunk_number' equal to 0 will return the last chunk in a set. jpayne@69: // Returns true if the chunk is found, false otherwise. Image related chunk jpayne@69: // payloads are accessed through WebPDemuxGetFrame() and related functions. jpayne@69: // Call WebPDemuxReleaseChunkIterator() when use of the iterator is complete. jpayne@69: // NOTE: 'dmux' must persist for the lifetime of the iterator. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPDemuxGetChunk(const WebPDemuxer* dmux, jpayne@69: const char fourcc[4], jpayne@69: int chunk_number, jpayne@69: WebPChunkIterator* iter); jpayne@69: jpayne@69: // Sets 'iter->chunk' to point to the next ('iter->chunk_num' + 1) or previous jpayne@69: // ('iter->chunk_num' - 1) chunk. These functions do not loop. jpayne@69: // Returns true on success, false otherwise. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPDemuxNextChunk(WebPChunkIterator* iter); jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPDemuxPrevChunk(WebPChunkIterator* iter); jpayne@69: jpayne@69: // Releases any memory associated with 'iter'. jpayne@69: // Must be called before destroying the associated WebPDemuxer with jpayne@69: // WebPDemuxDelete(). jpayne@69: WEBP_EXTERN void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // WebPAnimDecoder API jpayne@69: // jpayne@69: // This API allows decoding (possibly) animated WebP images. jpayne@69: // jpayne@69: // Code Example: jpayne@69: /* jpayne@69: WebPAnimDecoderOptions dec_options; jpayne@69: WebPAnimDecoderOptionsInit(&dec_options); jpayne@69: // Tune 'dec_options' as needed. jpayne@69: WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options); jpayne@69: WebPAnimInfo anim_info; jpayne@69: WebPAnimDecoderGetInfo(dec, &anim_info); jpayne@69: for (uint32_t i = 0; i < anim_info.loop_count; ++i) { jpayne@69: while (WebPAnimDecoderHasMoreFrames(dec)) { jpayne@69: uint8_t* buf; jpayne@69: int timestamp; jpayne@69: WebPAnimDecoderGetNext(dec, &buf, ×tamp); jpayne@69: // ... (Render 'buf' based on 'timestamp'). jpayne@69: // ... (Do NOT free 'buf', as it is owned by 'dec'). jpayne@69: } jpayne@69: WebPAnimDecoderReset(dec); jpayne@69: } jpayne@69: const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec); jpayne@69: // ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data). jpayne@69: WebPAnimDecoderDelete(dec); jpayne@69: */ jpayne@69: jpayne@69: typedef struct WebPAnimDecoder WebPAnimDecoder; // Main opaque object. jpayne@69: jpayne@69: // Global options. jpayne@69: struct WebPAnimDecoderOptions { jpayne@69: // Output colorspace. Only the following modes are supported: jpayne@69: // MODE_RGBA, MODE_BGRA, MODE_rgbA and MODE_bgrA. jpayne@69: WEBP_CSP_MODE color_mode; jpayne@69: int use_threads; // If true, use multi-threaded decoding. jpayne@69: uint32_t padding[7]; // Padding for later use. jpayne@69: }; jpayne@69: jpayne@69: // Internal, version-checked, entry point. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPAnimDecoderOptionsInitInternal( jpayne@69: WebPAnimDecoderOptions*, int); jpayne@69: jpayne@69: // Should always be called, to initialize a fresh WebPAnimDecoderOptions jpayne@69: // structure before modification. Returns false in case of version mismatch. jpayne@69: // WebPAnimDecoderOptionsInit() must have succeeded before using the jpayne@69: // 'dec_options' object. jpayne@69: WEBP_NODISCARD static WEBP_INLINE int WebPAnimDecoderOptionsInit( jpayne@69: WebPAnimDecoderOptions* dec_options) { jpayne@69: return WebPAnimDecoderOptionsInitInternal(dec_options, jpayne@69: WEBP_DEMUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: // Internal, version-checked, entry point. jpayne@69: WEBP_NODISCARD WEBP_EXTERN WebPAnimDecoder* WebPAnimDecoderNewInternal( jpayne@69: const WebPData*, const WebPAnimDecoderOptions*, int); jpayne@69: jpayne@69: // Creates and initializes a WebPAnimDecoder object. jpayne@69: // Parameters: jpayne@69: // webp_data - (in) WebP bitstream. This should remain unchanged during the jpayne@69: // lifetime of the output WebPAnimDecoder object. jpayne@69: // dec_options - (in) decoding options. Can be passed NULL to choose jpayne@69: // reasonable defaults (in particular, color mode MODE_RGBA jpayne@69: // will be picked). jpayne@69: // Returns: jpayne@69: // A pointer to the newly created WebPAnimDecoder object, or NULL in case of jpayne@69: // parsing error, invalid option or memory error. jpayne@69: WEBP_NODISCARD static WEBP_INLINE WebPAnimDecoder* WebPAnimDecoderNew( jpayne@69: const WebPData* webp_data, const WebPAnimDecoderOptions* dec_options) { jpayne@69: return WebPAnimDecoderNewInternal(webp_data, dec_options, jpayne@69: WEBP_DEMUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: // Global information about the animation.. jpayne@69: struct WebPAnimInfo { jpayne@69: uint32_t canvas_width; jpayne@69: uint32_t canvas_height; jpayne@69: uint32_t loop_count; jpayne@69: uint32_t bgcolor; jpayne@69: uint32_t frame_count; jpayne@69: uint32_t pad[4]; // padding for later use jpayne@69: }; jpayne@69: jpayne@69: // Get global information about the animation. jpayne@69: // Parameters: jpayne@69: // dec - (in) decoder instance to get information from. jpayne@69: // info - (out) global information fetched from the animation. jpayne@69: // Returns: jpayne@69: // True on success. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPAnimDecoderGetInfo( jpayne@69: const WebPAnimDecoder* dec, WebPAnimInfo* info); jpayne@69: jpayne@69: // Fetch the next frame from 'dec' based on options supplied to jpayne@69: // WebPAnimDecoderNew(). This will be a fully reconstructed canvas of size jpayne@69: // 'canvas_width * 4 * canvas_height', and not just the frame sub-rectangle. The jpayne@69: // returned buffer 'buf' is valid only until the next call to jpayne@69: // WebPAnimDecoderGetNext(), WebPAnimDecoderReset() or WebPAnimDecoderDelete(). jpayne@69: // Parameters: jpayne@69: // dec - (in/out) decoder instance from which the next frame is to be fetched. jpayne@69: // buf - (out) decoded frame. jpayne@69: // timestamp - (out) timestamp of the frame in milliseconds. jpayne@69: // Returns: jpayne@69: // False if any of the arguments are NULL, or if there is a parsing or jpayne@69: // decoding error, or if there are no more frames. Otherwise, returns true. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPAnimDecoderGetNext(WebPAnimDecoder* dec, jpayne@69: uint8_t** buf, jpayne@69: int* timestamp); jpayne@69: jpayne@69: // Check if there are more frames left to decode. jpayne@69: // Parameters: jpayne@69: // dec - (in) decoder instance to be checked. jpayne@69: // Returns: jpayne@69: // True if 'dec' is not NULL and some frames are yet to be decoded. jpayne@69: // Otherwise, returns false. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPAnimDecoderHasMoreFrames( jpayne@69: const WebPAnimDecoder* dec); jpayne@69: jpayne@69: // Resets the WebPAnimDecoder object, so that next call to jpayne@69: // WebPAnimDecoderGetNext() will restart decoding from 1st frame. This would be jpayne@69: // helpful when all frames need to be decoded multiple times (e.g. jpayne@69: // info.loop_count times) without destroying and recreating the 'dec' object. jpayne@69: // Parameters: jpayne@69: // dec - (in/out) decoder instance to be reset jpayne@69: WEBP_EXTERN void WebPAnimDecoderReset(WebPAnimDecoder* dec); jpayne@69: jpayne@69: // Grab the internal demuxer object. jpayne@69: // Getting the demuxer object can be useful if one wants to use operations only jpayne@69: // available through demuxer; e.g. to get XMP/EXIF/ICC metadata. The returned jpayne@69: // demuxer object is owned by 'dec' and is valid only until the next call to jpayne@69: // WebPAnimDecoderDelete(). jpayne@69: // jpayne@69: // Parameters: jpayne@69: // dec - (in) decoder instance from which the demuxer object is to be fetched. jpayne@69: WEBP_NODISCARD WEBP_EXTERN const WebPDemuxer* WebPAnimDecoderGetDemuxer( jpayne@69: const WebPAnimDecoder* dec); jpayne@69: jpayne@69: // Deletes the WebPAnimDecoder object. jpayne@69: // Parameters: jpayne@69: // dec - (in/out) decoder instance to be deleted jpayne@69: WEBP_EXTERN void WebPAnimDecoderDelete(WebPAnimDecoder* dec); jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: } // extern "C" jpayne@69: #endif jpayne@69: jpayne@69: #endif // WEBP_WEBP_DEMUX_H_