src/third_party/libwebp/webp/mux.h

   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)
  53 extern "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;
  62 typedef struct WebPMux WebPMux;   // main opaque object.
  63 typedef struct WebPMuxFrameInfo WebPMuxFrameInfo;
  64 typedef struct WebPMuxAnimParams WebPMuxAnimParams;
  65
  66 // Error codes
  67 typedef 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.
  77 typedef 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.
  95 WEBP_EXTERN(int) WebPGetMuxVersion(void);
  96
  97 //------------------------------------------------------------------------------
  98 // Life of a Mux object
  99
 100 // Internal, version-checked, entry point
 101 WEBP_EXTERN(WebPMux*) WebPNewInternal(int);
 102
 103 // Creates an empty mux object.
 104 // Returns:
 105 //   A pointer to the newly created empty mux object.
 106 static 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
 113 WEBP_EXTERN(void) WebPMuxDelete(WebPMux* mux);
 114
 115 //------------------------------------------------------------------------------
 116 // Mux creation.
 117
 118 // Internal, version-checked, entry point
 119 WEBP_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.
 129 static 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.
 156 WEBP_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.
 172 WEBP_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.
 185 WEBP_EXTERN(WebPMuxError) WebPMuxDeleteChunk(
 186     WebPMux* mux, const char fourcc[4]);
 187
 188 //------------------------------------------------------------------------------
 189 // Images.
 190
 191 // Encapsulates data about a single frame/fragment.
 192 struct 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.
 218 WEBP_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.
 238 WEBP_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.
 255 WEBP_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.
 268 WEBP_EXTERN(WebPMuxError) WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
 269
 270 //------------------------------------------------------------------------------
 271 // Animation.
 272
 273 // Animation parameters.
 274 struct 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.
 292 WEBP_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.
 303 WEBP_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.
 320 WEBP_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.
 331 WEBP_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
 349 WEBP_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_ */