OLD | NEW |
(Empty) | |
| 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 |
| 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_ */ |
OLD | NEW |