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