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 (at) google.com) 13 // Vikas (vikasa (at) 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 55 extern "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; 64 typedef struct WebPMux WebPMux; // main opaque object. 65 typedef struct WebPMuxFrameInfo WebPMuxFrameInfo; 66 typedef struct WebPMuxAnimParams WebPMuxAnimParams; 67 68 // Error codes 69 typedef 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. 79 typedef 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. 97 WEBP_EXTERN(int) WebPGetMuxVersion(void); 98 99 //------------------------------------------------------------------------------ 100 // Life of a Mux object 101 102 // Internal, version-checked, entry point 103 WEBP_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. 109 static 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 116 WEBP_EXTERN(void) WebPMuxDelete(WebPMux* mux); 117 118 //------------------------------------------------------------------------------ 119 // Mux creation. 120 121 // Internal, version-checked, entry point 122 WEBP_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. 132 static 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. 159 WEBP_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. 175 WEBP_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. 188 WEBP_EXTERN(WebPMuxError) WebPMuxDeleteChunk( 189 WebPMux* mux, const char fourcc[4]); 190 191 //------------------------------------------------------------------------------ 192 // Images. 193 194 // Encapsulates data about a single frame/fragment. 195 struct 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. 221 WEBP_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. 241 WEBP_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. 259 WEBP_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. 272 WEBP_EXTERN(WebPMuxError) WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth); 273 274 //------------------------------------------------------------------------------ 275 // Animation. 276 277 // Animation parameters. 278 struct 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. 296 WEBP_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. 307 WEBP_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. 329 WEBP_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. 345 WEBP_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. 361 WEBP_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. 372 WEBP_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. 390 WEBP_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