# WebP Container API Documentation RIFF container manipulation for WebP images. ## Mux API Allows manipulation of WebP container images, containing features like color profile, metadata, animation and fragmented images. ### Code Examples #### Create a MUX with Image Data, Color Profile and XMP Metadata int copy_data = 0; WebPMux* mux = WebPMuxNew(); // ... (Prepare image data). WebPMuxSetImage(mux, &image, copy_data); // ... (Prepare ICCP color profile data). WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data); // ... (Prepare XMP metadata). WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data); // Get data from mux in WebP RIFF format. WebPMuxAssemble(mux, &output_data); WebPMuxDelete(mux); // ... (Consume output_data; e.g. write output_data.bytes to file). WebPDataClear(&output_data); #### Get Image and Color Profile Data from a WebP File int copy_data = 0; // ... (Read data from file). WebPMux* mux = WebPMuxCreate(&data, copy_data); WebPMuxGetFrame(mux, 1, &image); // ... (Consume image; e.g. call WebPDecode() to decode the data). WebPMuxGetChunk(mux, "ICCP", &icc_profile); // ... (Consume icc_data). WebPMuxDelete(mux); free(data); ### Life of a Mux Object #### Enums // Error codes typedef enum WebPMuxError { WEBP_MUX_OK = 1, WEBP_MUX_NOT_FOUND = 0, WEBP_MUX_INVALID_ARGUMENT = -1, WEBP_MUX_BAD_DATA = -2, WEBP_MUX_MEMORY_ERROR = -3, WEBP_MUX_NOT_ENOUGH_DATA = -4 } WebPMuxError; // IDs for different types of chunks. typedef enum WebPChunkId { WEBP_CHUNK_VP8X, // VP8X WEBP_CHUNK_ICCP, // ICCP WEBP_CHUNK_ANIM, // ANIM WEBP_CHUNK_ANMF, // ANMF WEBP_CHUNK_ALPHA, // ALPH WEBP_CHUNK_IMAGE, // VP8/VP8L WEBP_CHUNK_EXIF, // EXIF WEBP_CHUNK_XMP, // XMP WEBP_CHUNK_UNKNOWN, // Other chunks. WEBP_CHUNK_NIL } WebPChunkId; #### `WebPGetMuxVersion()` Returns the version number of the mux library, packed in hexadecimal using 8 bits for each of major/minor/revision. E.g., v2.5.7 is `0x020507`. int WebPGetMuxVersion(void); #### `WebPMuxNew()` Creates an empty mux object. WebPMux* WebPMuxNew(void); Returns : A pointer to the newly created empty mux object. #### `WebPMuxDelete()` Deletes the mux object. void WebPMuxDelete(WebPMux* mux); Parameters : **mux** -- (in/out) object to be deleted ### Mux Creation #### `WebPMuxCreate()` Creates a mux object from raw data given in WebP RIFF format. WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data); Parameters : **bitstream** -- (in) the bitstream data in WebP RIFF format : **copy_data** -- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the **mux** object. Returns : **A pointer** to the mux object created from given data - on success. : **NULL** -- In case of invalid data or memory error. ### Non-Image Chunks #### `WebPMuxSetChunk()` Adds a chunk with id **fourcc** and data **chunk_data** in the mux object. Any existing chunk(s) with the same id will be removed. WebPMuxError WebPMuxSetChunk(WebPMux* mux, const char fourcc[4], const WebPData* chunk_data, int copy_data); **Note:** Only non-image related chunks should be managed through chunk APIs. (Image related chunks are: "ANMF", "FRGM", "VP8 ", "VP8L" and "ALPH"). To add, get and delete images, use [`WebPMuxSetImage()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxsetimage), [`WebPMuxPushFrame()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxpushframe), [`WebPMuxGetFrame()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxgetframe) and [`WebPMuxDeleteFrame()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxdeleteframe). Parameters : **mux** -- (in/out) object to which the chunk is to be added : **fourcc** -- (in) a character array containing the fourcc of the given chunk; e.g., "ICCP", "XMP ", "EXIF" etc. : **chunk_data** -- (in) the chunk data to be added : **copy_data** -- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the **mux** object. Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux, fourcc or chunk_data is NULL or if fourcc corresponds to an image chunk. : **`WEBP_MUX_MEMORY_ERROR`** -- on memory allocation error. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxGetChunk()` Gets a reference to the data of the chunk with id **fourcc** in the mux object. The caller should NOT free the returned data. WebPMuxError WebPMuxGetChunk(const WebPMux* mux, const char fourcc[4], WebPData* chunk_data); Parameters : **mux** -- (in) object from which the chunk data is to be fetched : **fourcc** -- (in) a character array containing the fourcc of the chunk; e.g., "ICCP", "XMP ", "EXIF" etc. : **chunk_data** -- (out) returned chunk data Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux, fourcc or chunk_data is NULL or if fourcc corresponds to an image chunk. : **`WEBP_MUX_NOT_FOUND`** -- If mux does not contain a chunk with the given id. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxDeleteChunk()` Deletes the chunk with the given **fourcc** from the mux object. WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]); Parameters : **mux** -- (in/out) object from which the chunk is to be deleted : **fourcc** -- (in) a character array containing the fourcc of the chunk; e.g., "ICCP", "XMP ", "EXIF" etc. Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux or fourcc is NULL or if fourcc corresponds to an image chunk. : **`WEBP_MUX_NOT_FOUND`** -- If mux does not contain a chunk with the given fourcc. : **`WEBP_MUX_OK`** -- on success. ### Images Encapsulates data about a single frame/fragment. struct WebPMuxFrameInfo { WebPData bitstream; // image data: can be a raw VP8/VP8L bitstream // or a single-image WebP file. int x_offset; // x-offset of the frame. int y_offset; // y-offset of the frame. int duration; // duration of the frame (in milliseconds). WebPChunkId id; // frame type: should be one of WEBP_CHUNK_ANMF, // WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE WebPMuxAnimDispose dispose_method; // Disposal method for the frame. WebPMuxAnimBlend blend_method; // Blend operation for the frame. }; #### `WebPMuxSetImage()` Sets the (non-animated and non-fragmented) image in the mux object. **Note:** Any existing images (including frames/fragments) will be removed. WebPMuxError WebPMuxSetImage(WebPMux* mux, const WebPData* bitstream, int copy_data); Parameters : **mux** -- (in/out) object in which the image is to be set : **bitstream** -- (in) can be a raw VP8/VP8L bitstream or a single-image WebP file (non-animated and non-fragmented) : **copy_data** -- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the **mux** object. Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux is NULL or bitstream is NULL. : **`WEBP_MUX_MEMORY_ERROR`** -- on memory allocation error. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxPushFrame()` Adds a frame at the end of the mux object. WebPMuxError WebPMuxPushFrame(WebPMux* mux, const WebPMuxFrameInfo* frame, int copy_data); **Notes:** 1. frame.id should be one of `WEBP_CHUNK_ANMF` or `WEBP_CHUNK_FRGM` 2. For setting a non-animated non-fragmented image, use [`WebPMuxSetImage()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxsetimage) instead. 3. Type of frame being pushed must be same as the frames in mux. 4. As WebP only supports even offsets, any odd offset will be snapped to an even location using: offset \&= \~1 Parameters : **mux** -- (in/out) object to which the frame is to be added : **frame** -- (in) frame data. : **copy_data** -- (in) value 1 indicates given data WILL be copied to the mux and value 0 indicates data will NOT be copied to the **mux** object. Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux or frame is NULL or if content of **frame** is invalid. : **`WEBP_MUX_MEMORY_ERROR`** -- on memory allocation error. : **`WEBP_MUX_OK`** -- on success. : **`WEBP_MUX_MEMORY_ERROR`** -- on memory allocation error. #### `WebPMuxGetFrame()` Gets the nth frame from the mux object. The content of **frame-\>bitstream** is allocated using malloc(), and NOT owned by the **mux** object. It MUST be deallocated by the caller by calling [`WebPDataClear()`](https://developers.google.com/speed/webp/docs/container-api#webpdataclear). nth=0 has a special meaning - last position. WebPMuxError WebPMuxGetFrame(const WebPMux* mux, uint32_t nth, WebPMuxFrameInfo* frame); Parameters : **mux** -- (in) object from which the info is to be fetched : **nth** -- (in) index of the frame in the mux object : **frame** -- (out) data of the returned frame Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux or frame is NULL. : **`WEBP_MUX_NOT_FOUND`** -- if there are less than nth frames in the mux object. : **`WEBP_MUX_BAD_DATA`** -- if nth frame chunk in mux is invalid. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxDeleteFrame()` Deletes a frame from the mux object. nth=0 has a special meaning - last position. WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth); Parameters : **mux** -- (in/out) object from which a frame is to be deleted : **nth** -- (in) The position from which the frame is to be deleted Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux is NULL. : **`WEBP_MUX_NOT_FOUND`** -- If there are less than nth frames in the mux object before deletion. : **`WEBP_MUX_OK`** -- on success. ### Animation #### Animation Parameters struct WebPMuxAnimParams { uint32_t bgcolor; // Background color of the canvas stored (in MSB order) as: // Bits 00 to 07: Alpha. // Bits 08 to 15: Red. // Bits 16 to 23: Green. // Bits 24 to 31: Blue. int loop_count; // Number of times to repeat the animation [0 = infinite]. }; #### `WebPMuxSetAnimationParams()` Sets the animation parameters in the mux object. Any existing ANIM chunks will be removed. WebPMuxError WebPMuxSetAnimationParams(WebPMux* mux, const WebPMuxAnimParams* params); Parameters : **mux** -- (in/out) object in which ANIM chunk is to be set/added : **params** -- (in) animation parameters. Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux or params is NULL. : **`WEBP_MUX_MEMORY_ERROR`** -- on memory allocation error. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxGetAnimationParams()` Gets the animation parameters from the mux object. WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux, WebPMuxAnimParams* params); Parameters : **mux** -- (in) object from which the animation parameters to be fetched : **params** -- (out) animation parameters extracted from the ANIM chunk Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux or params is NULL. : **`WEBP_MUX_NOT_FOUND`** -- if ANIM chunk is not present in mux object. : **`WEBP_MUX_OK`** -- on success. ### Misc. Utilities #### `WebPMuxGetCanvasSize()` Gets the canvas size from the mux object. WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux, int* width, int* height); **Note:** This method assumes that the VP8X chunk, if present, is up-to-date. That is, the mux object hasn't been modified since the last call to [`WebPMuxAssemble()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxassemble) or [`WebPMuxCreate()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxcreate). Parameters : **mux** -- (in) object from which the canvas size is to be fetched : **width** -- (out) canvas width : **height** -- (out) canvas height Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux, width or height is NULL. : **`WEBP_MUX_BAD_DATA`** -- if VP8X/VP8/VP8L chunk or canvas size is invalid. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxGetFeatures()` Gets the feature flags from the mux object. WebPMuxError WebPMuxGetFeatures(const WebPMux* mux, uint32_t* flags); **Note:** This method assumes that the VP8X chunk, if present, is up-to-date. That is, the mux object hasn't been modified since the last call to [`WebPMuxAssemble()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxassemble) or [`WebPMuxCreate()`](https://developers.google.com/speed/webp/docs/container-api#webpmuxcreate). Parameters : **mux** -- (in) object from which the features are to be fetched : **flags** -- (out) the flags specifying which features are present in the mux object. This will be an OR of various flag values. Enum `WebPFeatureFlags` can be used to test individual flag values. Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux or flags is NULL. : **`WEBP_MUX_BAD_DATA`** -- if VP8X/VP8/VP8L chunk or canvas size is invalid. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxNumChunks()` Gets the number of chunks having the given tag value in the **mux** object. WebPMuxError WebPMuxNumChunks(const WebPMux* mux, WebPChunkId id, int* num_elements); Parameters : **mux** -- (in) object from which the info is to be fetched : **id** -- (in) chunk id specifying the type of chunk : **num_elements** -- (out) number of chunks with the given chunk id Returns : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux, or num_elements is NULL. : **`WEBP_MUX_OK`** -- on success. #### `WebPMuxAssemble()` Assembles all chunks in WebP RIFF format and returns in **assembled_data**. This function also validates the mux object. WebPMuxError WebPMuxAssemble(WebPMux* mux, WebPData* assembled_data); **Note:** The content of **assembled_data** will be ignored and overwritten. Also, the content of **assembled_data** is allocated using malloc(), and NOT owned by the **mux** object. It MUST be deallocated by the caller by calling [`WebPDataClear()`](https://developers.google.com/speed/webp/docs/container-api#webpdataclear). Parameters : **mux** -- (in/out) object whose chunks are to be assembled : **assembled_data** -- (out) assembled WebP data Returns : **`WEBP_MUX_BAD_DATA`** -- if mux object is invalid. : **`WEBP_MUX_INVALID_ARGUMENT`** -- if mux or assembled_data is NULL. : **`WEBP_MUX_MEMORY_ERROR`** -- on memory allocation error. : **`WEBP_MUX_OK`** -- on success. ### WebPAnimEncoder API This API allows encoding (possibly) animated WebP images. **Code Example** WebPAnimEncoderOptions enc_options; WebPAnimEncoderOptionsInit(&enc_options); // Tune 'enc_options' as needed. WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options); while() { WebPConfig config; WebPConfigInit(&config); // Tune 'config' as needed. WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config); } WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL); WebPAnimEncoderAssemble(enc, webp_data); WebPAnimEncoderDelete(enc); // Write the 'webp_data' to a file, or re-mux it further. typedef struct WebPAnimEncoder WebPAnimEncoder; // Main opaque object. **Global Options** struct WebPAnimEncoderOptions { WebPMuxAnimParams anim_params; // Animation parameters. int minimize_size; // If true, minimize the output size (slow). Implicitly // disables key-frame insertion. int kmin; int kmax; // Minimum and maximum distance between consecutive key // frames in the output. The library may insert some key // frames as needed to satisfy this criteria. // Note that these conditions should hold: kmax > kmin // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then // key-frame insertion is disabled; and if kmax == 1, // then all frames will be key-frames (kmin value does // not matter for these special cases). int allow_mixed; // If true, use mixed compression mode; may choose // either lossy and lossless for each frame. int verbose; // If true, print info and warning messages to stderr. }; #### `WebPAnimEncoderOptionsInit()` Should always be called, to initialize a fresh **WebPAnimEncoderOptions** structure before modification. Returns false in case of version mismatch. WebPAnimEncoderOptionsInit() must have succeeded before using the **enc_options** object. Parameters : **enc_options** -- (in/out) options used for encoding animation Returns : True on success. int WebPAnimEncoderOptionsInit( WebPAnimEncoderOptions* enc_options); #### `WebPAnimEncoderNew()` Creates and initializes a WebPAnimEncoder object. Parameters : **width/height** -- (in) canvas width and height of the animation. : **enc_options** -- (in) encoding options; can be passed NULL to pick reasonable defaults. Returns : A pointer to the newly created **WebPAnimEncoder** object, or NULL in case of memory error. WebPAnimEncoder* WebPAnimEncoderNew( int width, int height, const WebPAnimEncoderOptions* enc_options); #### `WebPAnimEncoderAdd()` Optimize the given frame for WebP, encode it and add it to the **WebPAnimEncoder** object. The last call to **WebPAnimEncoderAdd** should be with `frame = NULL`, which indicates that no more frames are to be added. This call is also used to determine the duration of the last frame. Parameters : **enc** -- (in/out) object to which the frame is to be added. : **frame** -- (in/out) frame data in ARGB or YUV(A) format. If it is in YUV(A) format, it will be converted to ARGB, which incurs a small loss. : **timestamp_ms** -- (in) timestamp of this frame in milliseconds. Duration of a frame would be calculated as "timestamp of next frame - timestamp of this frame". Hence, timestamps should be in non-decreasing order. : **config** -- (in) encoding options; can be passed NULL to pick reasonable defaults. Returns : On error, returns false and `frame->error_code` is set appropriately. Otherwise, returns true. int WebPAnimEncoderAdd( WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms, const struct WebPConfig* config); #### `WebPAnimEncoderAssemble()` Assemble all frames added so far into a WebP bitstream. This call should be preceded by a call to **WebPAnimEncoderAdd** with `frame = NULL`; if not, the duration of the last frame will be internally estimated. Parameters : **enc** -- (in/out) object from which the frames are to be assembled. : **webp_data** -- (out) generated WebP bitstream. Returns : True on success. int WebPAnimEncoderAssemble(WebPAnimEncoder* enc, WebPData* webp_data); #### `WebPAnimEncoderGetError()` Get error string corresponding to the most recent call using **enc** . The returned string is owned by **enc** and is valid only until the next call to [`WebPAnimEncoderAdd()`](https://developers.google.com/speed/webp/docs/container-api#webpanimencoderadd) or [`WebPAnimEncoderAssemble()`](https://developers.google.com/speed/webp/docs/container-api#webpanimencoderassemble) or [`WebPAnimEncoderDelete()`](https://developers.google.com/speed/webp/docs/container-api#webpanimencoderdelete). Parameters : **enc** -- (in/out) object from which the error string is to be fetched. Returns : NULL if **enc** is NULL. Otherwise, returns the error string if the last call to **enc** had an error, or an empty string if the last call was a success. const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc); #### `WebPAnimEncoderDelete()` Deletes the **WebPAnimEncoder** object. Parameters : **enc** -- (in/out) object to be deleted void WebPAnimEncoderDelete(WebPAnimEncoder* enc); ## Demux API Enables extraction of image and extended format data from WebP files. ### Code Examples #### 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); ### Life of a Demux Object #### Enums 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; #### `WebPGetDemuxVersion()` Returns the version number of the demux library, packed in hexadecimal using 8 bits for each of major/minor/revision. E.g, v2.5.7 is `0x020507`. int WebPGetDemuxVersion(void); #### `WebPDemux()` Parses the full WebP file given by **data**. WebPDemuxer WebPDemux(const WebPData* data); Returns a `WebPDemuxer` object on successful parse, NULL otherwise. #### `WebPDemuxPartial()` 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. WebPDemuxer WebPDemuxPartial(const WebPData* data, WebPDemuxState* state); 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()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxdelete)) and [`WebPDemuxPartial()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxpartial) called again on the new data. This is usually an inexpensive operation. #### `WebPDemuxDelete()` Frees memory associated with **dmux**. void WebPDemuxDelete(WebPDemuxer* dmux); ### Data/Information Extraction typedef enum WebPFormatFeature { WEBP_FF_FORMAT_FLAGS, // bit-wise combination of WebPFeatureFlags // corresponding to the 'VP8X' chunk (if present). WEBP_FF_CANVAS_WIDTH, WEBP_FF_CANVAS_HEIGHT, WEBP_FF_LOOP_COUNT, // only relevant for animated file WEBP_FF_BACKGROUND_COLOR, // idem. 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; #### `WebPDemuxGetI()` Get the **feature** value from the **dmux**. uint32_t WebPDemuxGetI(const WebPDemuxer* dmux, WebPFormatFeature feature); **Note:** Values are only valid if [`WebPDemux()`](https://developers.google.com/speed/webp/docs/container-api#webpdemux) was used or [`WebPDemuxPartial()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxpartial) returned a state \> `WEBP_DEMUX_PARSING_HEADER`. ### Frame Iteration struct WebPIterator { int frame_num; int num_frames; // equivalent to WEBP_FF_FRAME_COUNT. int fragment_num; int num_fragments; int x_offset, y_offset; // offset relative to the canvas. int width, height; // dimensions of this frame or fragment. 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 or fragment given by 'frame_num' and // 'fragment_num'. int has_alpha; // True if the frame or fragment contains transparency. WebPMuxAnimBlend blend_method; // Blend operation for the frame. }; #### `WebPDemuxGetFrame()` Retrieves frame **frame_number** from **dmux**. int WebPDemuxGetFrame(const WebPDemuxer* dmux, int frame_number, WebPIterator* iter); **iter-\>fragment** points to the first fragment on return from this function. Individual fragments may be extracted using [`WebPDemuxSelectFragment()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxselectfragment). 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()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxreleaseiterator) when use of the iterator is complete. **Note:** **dmux** must persist for the lifetime of **iter**. #### `WebPDemuxNextFrame()`, `WebPDemuxPrevFrame()` Sets **iter-\>fragment** to point to the next (**iter-\>frame_num** + 1) or previous (**iter-\>frame_num** - 1) frame. These functions do not loop. int WebPDemuxNextFrame(WebPIterator* iter); int WebPDemuxPrevFrame(WebPIterator* iter); Returns true on success, false otherwise. #### `WebPDemuxSelectFragment()` Sets **iter-\>fragment** to reflect fragment number **fragment_num**. int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num); Returns true if fragment **fragment_num** is present, false otherwise. #### `WebPDemuxReleaseIterator()` Releases any memory associated with **iter**. void WebPDemuxReleaseIterator(WebPIterator* iter); Must be called before any subsequent calls to [`WebPDemuxGetChunk()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxgetchunk) on the same iter. Also, must be called before destroying the associated `WebPDemuxer` with [`WebPDemuxDelete()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxdelete). ### 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. }; #### `WebPDemuxGetChunk()` Retrieves the **chunk_number** instance of the chunk with id **fourcc** from **dmux**. int WebPDemuxGetChunk(const WebPDemuxer* dmux, const char fourcc[4], int chunk_number, WebPChunkIterator* iter); **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()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxgetframe) and related functions. Call [`WebPDemuxReleaseChunkIterator()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxreleasechunkiterator) when use of the iterator is complete. **Note:** **dmux** must persist for the lifetime of the iterator. #### `WebPDemuxNextChunk()`, `WebPDemuxPrevChunk()` Sets **iter-\>chunk** to point to the next (**iter-\>chunk_num** + 1) or previous (**iter-\>chunk_num** - 1) chunk. These functions do not loop. int WebPDemuxNextChunk(WebPChunkIterator* iter); int WebPDemuxPrevChunk(WebPChunkIterator* iter); Returns true on success, false otherwise. #### `WebPDemuxReleaseChunkIterator()` Releases any memory associated with **iter**. void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter); Must be called before destroying the associated `WebPDemuxer` with [`WebPDemuxDelete()`](https://developers.google.com/speed/webp/docs/container-api#webpdemuxdelete). ### 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. }; #### `WebPAnimDecoderOptionsInit()` 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. Parameters **dec_options** -- (in/out) options used for decoding animation Returns : True on success int WebPAnimDecoderOptionsInit( WebPAnimDecoderOptions* dec_options); #### `WebPAnimDecoderNew()` 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. WebPAnimDecoder* WebPAnimDecoderNew( const WebPData* webp_data, const WebPAnimDecoderOptions* dec_options); 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; }; #### `WebPAnimDecoderGetInfo()` 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. int WebPAnimDecoderGetInfo(const WebPAnimDecoder* dec, WebPAnimInfo* info); #### `WebPAnimDecoderGetNext()` Fetch the next frame from **dec** based on options supplied to [`WebPAnimDecoderNew()`](https://developers.google.com/speed/webp/docs/container-api#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()`](https://developers.google.com/speed/webp/docs/container-api#webpanimdecoderreset) or [`WebPAnimDecoderDelete()`](https://developers.google.com/speed/webp/docs/container-api#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. int WebPAnimDecoderGetNext(WebPAnimDecoder* dec, uint8_t** buf, int* timestamp); #### `WebPAnimDecoderHasMoreFrames()` 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. int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec); #### `WebPAnimDecoderReset()` Resets the WebPAnimDecoder object, so that next call to [`WebPAnimDecoderGetNext()`](https://developers.google.com/speed/webp/docs/container-api#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 void WebPAnimDecoderReset(WebPAnimDecoder* dec); #### `WebPAnimDecoderGetDemuxer()` 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()`](https://developers.google.com/speed/webp/docs/container-api#webpanimdecoderdelete). Parameters : **dec** -- (in) decoder instance from which the demuxer object is to be fetched. const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec); #### `WebPAnimDecoderDelete()` Deletes the **WebPAnimDecoder** object. Parameters : **dec** -- (in/out) decoder instance to be deleted. Returns : True on success. void WebPAnimDecoderDelete(WebPAnimDecoder* dec); ## Common Data Types #### Enums typedef enum WebPFeatureFlags { FRAGMENTS_FLAG = 0x00000001, ANIMATION_FLAG = 0x00000002, XMP_FLAG = 0x00000004, EXIF_FLAG = 0x00000008, ALPHA_FLAG = 0x00000010, ICCP_FLAG = 0x00000020 } WebPFeatureFlags; // Dispose method (animation only). Indicates how the area used by the current // frame is to be treated before rendering the next frame on the canvas. typedef enum WebPMuxAnimDispose { WEBP_MUX_DISPOSE_NONE, // Do not dispose. WEBP_MUX_DISPOSE_BACKGROUND // Dispose to background color. } WebPMuxAnimDispose; // Blend operation (animation only). Indicates how transparent pixels of the // current frame are blended with those of the previous canvas. typedef enum WebPMuxAnimBlend { WEBP_MUX_BLEND, // Blend. WEBP_MUX_NO_BLEND // Do not blend. } WebPMuxAnimBlend; #### `WebPDataInit()` Initializes the contents of the **webp_data** object with default values. void WebPDataInit(WebPData* webp_data); #### `WebPDataClear()` Clears the contents of the **webp_data** object by calling `free()`. Does not deallocate the object itself. void WebPDataClear(WebPData* webp_data); #### `WebPDataCopy()` Allocates necessary storage for **dst** and copies the contents of **src**. Returns true on success. int WebPDataCopy(const WebPData* src, WebPData* dst);