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