1// Copyright 2011 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// RIFF container manipulation for WEBP images. 11// 12// Authors: Urvang (urvang@google.com) 13// Vikas (vikasa@google.com) 14 15// This API allows manipulation of WebP container images containing features 16// like color profile, metadata, animation and fragmented images. 17// 18// Code Example#1: Creating a MUX with image data, color profile and XMP 19// metadata. 20// 21// int copy_data = 0; 22// WebPMux* mux = WebPMuxNew(); 23// // ... (Prepare image data). 24// WebPMuxSetImage(mux, &image, copy_data); 25// // ... (Prepare ICCP color profile data). 26// WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data); 27// // ... (Prepare XMP metadata). 28// WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data); 29// // Get data from mux in WebP RIFF format. 30// WebPMuxAssemble(mux, &output_data); 31// WebPMuxDelete(mux); 32// // ... (Consume output_data; e.g. write output_data.bytes to file). 33// WebPDataClear(&output_data); 34// 35// Code Example#2: Get image and color profile data from a WebP file. 36// 37// int copy_data = 0; 38// // ... (Read data from file). 39// WebPMux* mux = WebPMuxCreate(&data, copy_data); 40// WebPMuxGetFrame(mux, 1, &image); 41// // ... (Consume image; e.g. call WebPDecode() to decode the data). 42// WebPMuxGetChunk(mux, "ICCP", &icc_profile); 43// // ... (Consume icc_data). 44// WebPMuxDelete(mux); 45// free(data); 46 47#ifndef WEBP_WEBP_MUX_H_ 48#define WEBP_WEBP_MUX_H_ 49 50#include "./mux_types.h" 51 52#if defined(__cplusplus) || defined(c_plusplus) 53extern "C" { 54#endif 55 56#define WEBP_MUX_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 WebPMuxError WebPMuxError; 61// typedef enum WebPChunkId WebPChunkId; 62typedef struct WebPMux WebPMux; // main opaque object. 63typedef struct WebPMuxFrameInfo WebPMuxFrameInfo; 64typedef struct WebPMuxAnimParams WebPMuxAnimParams; 65 66// Error codes 67typedef enum WebPMuxError { 68 WEBP_MUX_OK = 1, 69 WEBP_MUX_NOT_FOUND = 0, 70 WEBP_MUX_INVALID_ARGUMENT = -1, 71 WEBP_MUX_BAD_DATA = -2, 72 WEBP_MUX_MEMORY_ERROR = -3, 73 WEBP_MUX_NOT_ENOUGH_DATA = -4 74} WebPMuxError; 75 76// IDs for different types of chunks. 77typedef enum WebPChunkId { 78 WEBP_CHUNK_VP8X, // VP8X 79 WEBP_CHUNK_ICCP, // ICCP 80 WEBP_CHUNK_ANIM, // ANIM 81 WEBP_CHUNK_ANMF, // ANMF 82 WEBP_CHUNK_FRGM, // FRGM 83 WEBP_CHUNK_ALPHA, // ALPH 84 WEBP_CHUNK_IMAGE, // VP8/VP8L 85 WEBP_CHUNK_EXIF, // EXIF 86 WEBP_CHUNK_XMP, // XMP 87 WEBP_CHUNK_UNKNOWN, // Other chunks. 88 WEBP_CHUNK_NIL 89} WebPChunkId; 90 91//------------------------------------------------------------------------------ 92 93// Returns the version number of the mux library, packed in hexadecimal using 94// 8bits or each of major/minor/revision. E.g: v2.5.7 is 0x020507. 95WEBP_EXTERN(int) WebPGetMuxVersion(void); 96 97//------------------------------------------------------------------------------ 98// Life of a Mux object 99 100// Internal, version-checked, entry point 101WEBP_EXTERN(WebPMux*) WebPNewInternal(int); 102 103// Creates an empty mux object. 104// Returns: 105// A pointer to the newly created empty mux object. 106static WEBP_INLINE WebPMux* WebPMuxNew(void) { 107 return WebPNewInternal(WEBP_MUX_ABI_VERSION); 108} 109 110// Deletes the mux object. 111// Parameters: 112// mux - (in/out) object to be deleted 113WEBP_EXTERN(void) WebPMuxDelete(WebPMux* mux); 114 115//------------------------------------------------------------------------------ 116// Mux creation. 117 118// Internal, version-checked, entry point 119WEBP_EXTERN(WebPMux*) WebPMuxCreateInternal(const WebPData*, int, int); 120 121// Creates a mux object from raw data given in WebP RIFF format. 122// Parameters: 123// bitstream - (in) the bitstream data in WebP RIFF format 124// copy_data - (in) value 1 indicates given data WILL be copied to the mux 125// and value 0 indicates data will NOT be copied. 126// Returns: 127// A pointer to the mux object created from given data - on success. 128// NULL - In case of invalid data or memory error. 129static WEBP_INLINE WebPMux* WebPMuxCreate(const WebPData* bitstream, 130 int copy_data) { 131 return WebPMuxCreateInternal(bitstream, copy_data, WEBP_MUX_ABI_VERSION); 132} 133 134//------------------------------------------------------------------------------ 135// Non-image chunks. 136 137// Note: Only non-image related chunks should be managed through chunk APIs. 138// (Image related chunks are: "ANMF", "FRGM", "VP8 ", "VP8L" and "ALPH"). 139// To add, get and delete images, use APIs WebPMuxSetImage(), 140// WebPMuxPushFrame(), WebPMuxGetFrame() and WebPMuxDeleteFrame(). 141 142// Adds a chunk with id 'fourcc' and data 'chunk_data' in the mux object. 143// Any existing chunk(s) with the same id will be removed. 144// Parameters: 145// mux - (in/out) object to which the chunk is to be added 146// fourcc - (in) a character array containing the fourcc of the given chunk; 147// e.g., "ICCP", "XMP ", "EXIF" etc. 148// chunk_data - (in) the chunk data to be added 149// copy_data - (in) value 1 indicates given data WILL be copied to the mux 150// and value 0 indicates data will NOT be copied. 151// Returns: 152// WEBP_MUX_INVALID_ARGUMENT - if mux, fourcc or chunk_data is NULL 153// or if fourcc corresponds to an image chunk. 154// WEBP_MUX_MEMORY_ERROR - on memory allocation error. 155// WEBP_MUX_OK - on success. 156WEBP_EXTERN(WebPMuxError) WebPMuxSetChunk( 157 WebPMux* mux, const char fourcc[4], const WebPData* chunk_data, 158 int copy_data); 159 160// Gets a reference to the data of the chunk with id 'fourcc' in the mux object. 161// The caller should NOT free the returned data. 162// Parameters: 163// mux - (in) object from which the chunk data is to be fetched 164// fourcc - (in) a character array containing the fourcc of the chunk; 165// e.g., "ICCP", "XMP ", "EXIF" etc. 166// chunk_data - (out) returned chunk data 167// Returns: 168// WEBP_MUX_INVALID_ARGUMENT - if either mux, fourcc or chunk_data is NULL 169// or if fourcc corresponds to an image chunk. 170// WEBP_MUX_NOT_FOUND - If mux does not contain a chunk with the given id. 171// WEBP_MUX_OK - on success. 172WEBP_EXTERN(WebPMuxError) WebPMuxGetChunk( 173 const WebPMux* mux, const char fourcc[4], WebPData* chunk_data); 174 175// Deletes the chunk with the given 'fourcc' from the mux object. 176// Parameters: 177// mux - (in/out) object from which the chunk is to be deleted 178// fourcc - (in) a character array containing the fourcc of the chunk; 179// e.g., "ICCP", "XMP ", "EXIF" etc. 180// Returns: 181// WEBP_MUX_INVALID_ARGUMENT - if mux or fourcc is NULL 182// or if fourcc corresponds to an image chunk. 183// WEBP_MUX_NOT_FOUND - If mux does not contain a chunk with the given fourcc. 184// WEBP_MUX_OK - on success. 185WEBP_EXTERN(WebPMuxError) WebPMuxDeleteChunk( 186 WebPMux* mux, const char fourcc[4]); 187 188//------------------------------------------------------------------------------ 189// Images. 190 191// Encapsulates data about a single frame/fragment. 192struct WebPMuxFrameInfo { 193 WebPData bitstream; // image data: can either be a raw VP8/VP8L bitstream 194 // or a single-image WebP file. 195 int x_offset; // x-offset of the frame. 196 int y_offset; // y-offset of the frame. 197 int duration; // duration of the frame (in milliseconds). 198 199 WebPChunkId id; // frame type: should be one of WEBP_CHUNK_ANMF, 200 // WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE 201 WebPMuxAnimDispose dispose_method; // Disposal method for the frame. 202 WebPMuxAnimBlend blend_method; // Blend operation for the frame. 203 uint32_t pad[1]; // padding for later use 204}; 205 206// Sets the (non-animated and non-fragmented) image in the mux object. 207// Note: Any existing images (including frames/fragments) will be removed. 208// Parameters: 209// mux - (in/out) object in which the image is to be set 210// bitstream - (in) can either be a raw VP8/VP8L bitstream or a single-image 211// WebP file (non-animated and non-fragmented) 212// copy_data - (in) value 1 indicates given data WILL be copied to the mux 213// and value 0 indicates data will NOT be copied. 214// Returns: 215// WEBP_MUX_INVALID_ARGUMENT - if mux is NULL or bitstream is NULL. 216// WEBP_MUX_MEMORY_ERROR - on memory allocation error. 217// WEBP_MUX_OK - on success. 218WEBP_EXTERN(WebPMuxError) WebPMuxSetImage( 219 WebPMux* mux, const WebPData* bitstream, int copy_data); 220 221// Adds a frame at the end of the mux object. 222// Notes: (1) frame.id should be one of WEBP_CHUNK_ANMF or WEBP_CHUNK_FRGM 223// (2) For setting a non-animated non-fragmented image, use 224// WebPMuxSetImage() instead. 225// (3) Type of frame being pushed must be same as the frames in mux. 226// (4) As WebP only supports even offsets, any odd offset will be snapped 227// to an even location using: offset &= ~1 228// Parameters: 229// mux - (in/out) object to which the frame is to be added 230// frame - (in) frame data. 231// copy_data - (in) value 1 indicates given data WILL be copied to the mux 232// and value 0 indicates data will NOT be copied. 233// Returns: 234// WEBP_MUX_INVALID_ARGUMENT - if mux or frame is NULL 235// or if content of 'frame' is invalid. 236// WEBP_MUX_MEMORY_ERROR - on memory allocation error. 237// WEBP_MUX_OK - on success. 238WEBP_EXTERN(WebPMuxError) WebPMuxPushFrame( 239 WebPMux* mux, const WebPMuxFrameInfo* frame, int copy_data); 240 241// Gets the nth frame from the mux object. 242// The content of 'frame->bitstream' is allocated using malloc(), and NOT 243// owned by the 'mux' object. It MUST be deallocated by the caller by calling 244// WebPDataClear(). 245// nth=0 has a special meaning - last position. 246// Parameters: 247// mux - (in) object from which the info is to be fetched 248// nth - (in) index of the frame in the mux object 249// frame - (out) data of the returned frame 250// Returns: 251// WEBP_MUX_INVALID_ARGUMENT - if mux or frame is NULL. 252// WEBP_MUX_NOT_FOUND - if there are less than nth frames in the mux object. 253// WEBP_MUX_BAD_DATA - if nth frame chunk in mux is invalid. 254// WEBP_MUX_OK - on success. 255WEBP_EXTERN(WebPMuxError) WebPMuxGetFrame( 256 const WebPMux* mux, uint32_t nth, WebPMuxFrameInfo* frame); 257 258// Deletes a frame from the mux object. 259// nth=0 has a special meaning - last position. 260// Parameters: 261// mux - (in/out) object from which a frame is to be deleted 262// nth - (in) The position from which the frame is to be deleted 263// Returns: 264// WEBP_MUX_INVALID_ARGUMENT - if mux is NULL. 265// WEBP_MUX_NOT_FOUND - If there are less than nth frames in the mux object 266// before deletion. 267// WEBP_MUX_OK - on success. 268WEBP_EXTERN(WebPMuxError) WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth); 269 270//------------------------------------------------------------------------------ 271// Animation. 272 273// Animation parameters. 274struct WebPMuxAnimParams { 275 uint32_t bgcolor; // Background color of the canvas stored (in MSB order) as: 276 // Bits 00 to 07: Alpha. 277 // Bits 08 to 15: Red. 278 // Bits 16 to 23: Green. 279 // Bits 24 to 31: Blue. 280 int loop_count; // Number of times to repeat the animation [0 = infinite]. 281}; 282 283// Sets the animation parameters in the mux object. Any existing ANIM chunks 284// will be removed. 285// Parameters: 286// mux - (in/out) object in which ANIM chunk is to be set/added 287// params - (in) animation parameters. 288// Returns: 289// WEBP_MUX_INVALID_ARGUMENT - if either mux or params is NULL 290// WEBP_MUX_MEMORY_ERROR - on memory allocation error. 291// WEBP_MUX_OK - on success. 292WEBP_EXTERN(WebPMuxError) WebPMuxSetAnimationParams( 293 WebPMux* mux, const WebPMuxAnimParams* params); 294 295// Gets the animation parameters from the mux object. 296// Parameters: 297// mux - (in) object from which the animation parameters to be fetched 298// params - (out) animation parameters extracted from the ANIM chunk 299// Returns: 300// WEBP_MUX_INVALID_ARGUMENT - if either of mux or params is NULL 301// WEBP_MUX_NOT_FOUND - if ANIM chunk is not present in mux object. 302// WEBP_MUX_OK - on success. 303WEBP_EXTERN(WebPMuxError) WebPMuxGetAnimationParams( 304 const WebPMux* mux, WebPMuxAnimParams* params); 305 306//------------------------------------------------------------------------------ 307// Misc Utilities. 308 309// Gets the feature flags from the mux object. 310// Parameters: 311// mux - (in) object from which the features are to be fetched 312// flags - (out) the flags specifying which features are present in the 313// mux object. This will be an OR of various flag values. 314// Enum 'WebPFeatureFlags' can be used to test individual flag values. 315// Returns: 316// WEBP_MUX_INVALID_ARGUMENT - if mux or flags is NULL 317// WEBP_MUX_NOT_FOUND - if VP8X chunk is not present in mux object. 318// WEBP_MUX_BAD_DATA - if VP8X chunk in mux is invalid. 319// WEBP_MUX_OK - on success. 320WEBP_EXTERN(WebPMuxError) WebPMuxGetFeatures(const WebPMux* mux, 321 uint32_t* flags); 322 323// Gets number of chunks having tag value tag in the mux object. 324// Parameters: 325// mux - (in) object from which the info is to be fetched 326// id - (in) chunk id specifying the type of chunk 327// num_elements - (out) number of chunks with the given chunk id 328// Returns: 329// WEBP_MUX_INVALID_ARGUMENT - if either mux, or num_elements is NULL 330// WEBP_MUX_OK - on success. 331WEBP_EXTERN(WebPMuxError) WebPMuxNumChunks(const WebPMux* mux, 332 WebPChunkId id, int* num_elements); 333 334// Assembles all chunks in WebP RIFF format and returns in 'assembled_data'. 335// This function also validates the mux object. 336// Note: The content of 'assembled_data' will be ignored and overwritten. 337// Also, the content of 'assembled_data' is allocated using malloc(), and NOT 338// owned by the 'mux' object. It MUST be deallocated by the caller by calling 339// WebPDataClear(). 340// Parameters: 341// mux - (in/out) object whose chunks are to be assembled 342// assembled_data - (out) assembled WebP data 343// Returns: 344// WEBP_MUX_BAD_DATA - if mux object is invalid. 345// WEBP_MUX_INVALID_ARGUMENT - if either mux, output_data or output_size is 346// NULL. 347// WEBP_MUX_MEMORY_ERROR - on memory allocation error. 348// WEBP_MUX_OK - on success 349WEBP_EXTERN(WebPMuxError) WebPMuxAssemble(WebPMux* mux, 350 WebPData* assembled_data); 351 352//------------------------------------------------------------------------------ 353 354#if defined(__cplusplus) || defined(c_plusplus) 355} // extern "C" 356#endif 357 358#endif /* WEBP_WEBP_MUX_H_ */ 359