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 and encoding for WebP images.
11//
12// Authors: Urvang (urvang@google.com)
13// Vikas (vikasa@google.com)
14
15#ifndef WEBP_WEBP_MUX_H_
16#define WEBP_WEBP_MUX_H_
17
18#include "./mux_types.h"
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24#define WEBP_MUX_ABI_VERSION 0x0108 // MAJOR(8b) + MINOR(8b)
25
26//------------------------------------------------------------------------------
27// Mux API
28//
29// This API allows manipulation of WebP container images containing features
30// like color profile, metadata, animation.
31//
32// Code Example#1: Create a WebPMux object with image data, color profile and
33// XMP metadata.
34/*
35 int copy_data = 0;
36 WebPMux* mux = WebPMuxNew();
37 // ... (Prepare image data).
38 WebPMuxSetImage(mux, &image, copy_data);
39 // ... (Prepare ICCP color profile data).
40 WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
41 // ... (Prepare XMP metadata).
42 WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
43 // Get data from mux in WebP RIFF format.
44 WebPMuxAssemble(mux, &output_data);
45 WebPMuxDelete(mux);
46 // ... (Consume output_data; e.g. write output_data.bytes to file).
47 WebPDataClear(&output_data);
48*/
49
50// Code Example#2: Get image and color profile data from a WebP file.
51/*
52 int copy_data = 0;
53 // ... (Read data from file).
54 WebPMux* mux = WebPMuxCreate(&data, copy_data);
55 WebPMuxGetFrame(mux, 1, &image);
56 // ... (Consume image; e.g. call WebPDecode() to decode the data).
57 WebPMuxGetChunk(mux, "ICCP", &icc_profile);
58 // ... (Consume icc_data).
59 WebPMuxDelete(mux);
60 WebPFree(data);
61*/
62
63// Note: forward declaring enumerations is not allowed in (strict) C and C++,
64// the types are left here for reference.
65// typedef enum WebPMuxError WebPMuxError;
66// typedef enum WebPChunkId WebPChunkId;
67typedef struct WebPMux WebPMux; // main opaque object.
68typedef struct WebPMuxFrameInfo WebPMuxFrameInfo;
69typedef struct WebPMuxAnimParams WebPMuxAnimParams;
70typedef struct WebPAnimEncoderOptions WebPAnimEncoderOptions;
71
72// Error codes
73typedef enum WebPMuxError {
74 WEBP_MUX_OK = 1,
75 WEBP_MUX_NOT_FOUND = 0,
76 WEBP_MUX_INVALID_ARGUMENT = -1,
77 WEBP_MUX_BAD_DATA = -2,
78 WEBP_MUX_MEMORY_ERROR = -3,
79 WEBP_MUX_NOT_ENOUGH_DATA = -4
80} WebPMuxError;
81
82// IDs for different types of chunks.
83typedef enum WebPChunkId {
84 WEBP_CHUNK_VP8X, // VP8X
85 WEBP_CHUNK_ICCP, // ICCP
86 WEBP_CHUNK_ANIM, // ANIM
87 WEBP_CHUNK_ANMF, // ANMF
88 WEBP_CHUNK_DEPRECATED, // (deprecated from FRGM)
89 WEBP_CHUNK_ALPHA, // ALPH
90 WEBP_CHUNK_IMAGE, // VP8/VP8L
91 WEBP_CHUNK_EXIF, // EXIF
92 WEBP_CHUNK_XMP, // XMP
93 WEBP_CHUNK_UNKNOWN, // Other chunks.
94 WEBP_CHUNK_NIL
95} WebPChunkId;
96
97//------------------------------------------------------------------------------
98
99// Returns the version number of the mux library, packed in hexadecimal using
100// 8bits for each of major/minor/revision. E.g: v2.5.7 is 0x020507.
101WEBP_EXTERN int WebPGetMuxVersion(void);
102
103//------------------------------------------------------------------------------
104// Life of a Mux object
105
106// Internal, version-checked, entry point
107WEBP_EXTERN WebPMux* WebPNewInternal(int);
108
109// Creates an empty mux object.
110// Returns:
111// A pointer to the newly created empty mux object.
112// Or NULL in case of memory error.
113static WEBP_INLINE WebPMux* WebPMuxNew(void) {
114 return WebPNewInternal(WEBP_MUX_ABI_VERSION);
115}
116
117// Deletes the mux object.
118// Parameters:
119// mux - (in/out) object to be deleted
120WEBP_EXTERN void WebPMuxDelete(WebPMux* mux);
121
122//------------------------------------------------------------------------------
123// Mux creation.
124
125// Internal, version-checked, entry point
126WEBP_EXTERN WebPMux* WebPMuxCreateInternal(const WebPData*, int, int);
127
128// Creates a mux object from raw data given in WebP RIFF format.
129// Parameters:
130// bitstream - (in) the bitstream data in WebP RIFF format
131// copy_data - (in) value 1 indicates given data WILL be copied to the mux
132// object and value 0 indicates data will NOT be copied.
133// Returns:
134// A pointer to the mux object created from given data - on success.
135// NULL - In case of invalid data or memory error.
136static WEBP_INLINE WebPMux* WebPMuxCreate(const WebPData* bitstream,
137 int copy_data) {
138 return WebPMuxCreateInternal(bitstream, copy_data, WEBP_MUX_ABI_VERSION);
139}
140
141//------------------------------------------------------------------------------
142// Non-image chunks.
143
144// Note: Only non-image related chunks should be managed through chunk APIs.
145// (Image related chunks are: "ANMF", "VP8 ", "VP8L" and "ALPH").
146// To add, get and delete images, use WebPMuxSetImage(), WebPMuxPushFrame(),
147// WebPMuxGetFrame() and WebPMuxDeleteFrame().
148
149// Adds a chunk with id 'fourcc' and data 'chunk_data' in the mux object.
150// Any existing chunk(s) with the same id will be removed.
151// Parameters:
152// mux - (in/out) object to which the chunk is to be added
153// fourcc - (in) a character array containing the fourcc of the given chunk;
154// e.g., "ICCP", "XMP ", "EXIF" etc.
155// chunk_data - (in) the chunk data to be added
156// copy_data - (in) value 1 indicates given data WILL be copied to the mux
157// object and value 0 indicates data will NOT be copied.
158// Returns:
159// WEBP_MUX_INVALID_ARGUMENT - if mux, fourcc or chunk_data is NULL
160// or if fourcc corresponds to an image chunk.
161// WEBP_MUX_MEMORY_ERROR - on memory allocation error.
162// WEBP_MUX_OK - on success.
163WEBP_EXTERN WebPMuxError WebPMuxSetChunk(
164 WebPMux* mux, const char fourcc[4], const WebPData* chunk_data,
165 int copy_data);
166
167// Gets a reference to the data of the chunk with id 'fourcc' in the mux object.
168// The caller should NOT free the returned data.
169// Parameters:
170// mux - (in) object from which the chunk data is to be fetched
171// fourcc - (in) a character array containing the fourcc of the chunk;
172// e.g., "ICCP", "XMP ", "EXIF" etc.
173// chunk_data - (out) returned chunk data
174// Returns:
175// WEBP_MUX_INVALID_ARGUMENT - if mux, fourcc or chunk_data is NULL
176// or if fourcc corresponds to an image chunk.
177// WEBP_MUX_NOT_FOUND - If mux does not contain a chunk with the given id.
178// WEBP_MUX_OK - on success.
179WEBP_EXTERN WebPMuxError WebPMuxGetChunk(
180 const WebPMux* mux, const char fourcc[4], WebPData* chunk_data);
181
182// Deletes the chunk with the given 'fourcc' from the mux object.
183// Parameters:
184// mux - (in/out) object from which the chunk is to be deleted
185// fourcc - (in) a character array containing the fourcc of the chunk;
186// e.g., "ICCP", "XMP ", "EXIF" etc.
187// Returns:
188// WEBP_MUX_INVALID_ARGUMENT - if mux or fourcc is NULL
189// or if fourcc corresponds to an image chunk.
190// WEBP_MUX_NOT_FOUND - If mux does not contain a chunk with the given fourcc.
191// WEBP_MUX_OK - on success.
192WEBP_EXTERN WebPMuxError WebPMuxDeleteChunk(
193 WebPMux* mux, const char fourcc[4]);
194
195//------------------------------------------------------------------------------
196// Images.
197
198// Encapsulates data about a single frame.
199struct WebPMuxFrameInfo {
200 WebPData bitstream; // image data: can be a raw VP8/VP8L bitstream
201 // or a single-image WebP file.
202 int x_offset; // x-offset of the frame.
203 int y_offset; // y-offset of the frame.
204 int duration; // duration of the frame (in milliseconds).
205
206 WebPChunkId id; // frame type: should be one of WEBP_CHUNK_ANMF
207 // or WEBP_CHUNK_IMAGE
208 WebPMuxAnimDispose dispose_method; // Disposal method for the frame.
209 WebPMuxAnimBlend blend_method; // Blend operation for the frame.
210 uint32_t pad[1]; // padding for later use
211};
212
213// Sets the (non-animated) image in the mux object.
214// Note: Any existing images (including frames) will be removed.
215// Parameters:
216// mux - (in/out) object in which the image is to be set
217// bitstream - (in) can be a raw VP8/VP8L bitstream or a single-image
218// WebP file (non-animated)
219// copy_data - (in) value 1 indicates given data WILL be copied to the mux
220// object and value 0 indicates data will NOT be copied.
221// Returns:
222// WEBP_MUX_INVALID_ARGUMENT - if mux is NULL or bitstream is NULL.
223// WEBP_MUX_MEMORY_ERROR - on memory allocation error.
224// WEBP_MUX_OK - on success.
225WEBP_EXTERN WebPMuxError WebPMuxSetImage(
226 WebPMux* mux, const WebPData* bitstream, int copy_data);
227
228// Adds a frame at the end of the mux object.
229// Notes: (1) frame.id should be WEBP_CHUNK_ANMF
230// (2) For setting a non-animated image, use WebPMuxSetImage() instead.
231// (3) Type of frame being pushed must be same as the frames in mux.
232// (4) As WebP only supports even offsets, any odd offset will be snapped
233// to an even location using: offset &= ~1
234// Parameters:
235// mux - (in/out) object to which the frame is to be added
236// frame - (in) frame data.
237// copy_data - (in) value 1 indicates given data WILL be copied to the mux
238// object and value 0 indicates data will NOT be copied.
239// Returns:
240// WEBP_MUX_INVALID_ARGUMENT - if mux or frame is NULL
241// or if content of 'frame' is invalid.
242// WEBP_MUX_MEMORY_ERROR - on memory allocation error.
243// WEBP_MUX_OK - on success.
244WEBP_EXTERN WebPMuxError WebPMuxPushFrame(
245 WebPMux* mux, const WebPMuxFrameInfo* frame, int copy_data);
246
247// Gets the nth frame from the mux object.
248// The content of 'frame->bitstream' is allocated using WebPMalloc(), and NOT
249// owned by the 'mux' object. It MUST be deallocated by the caller by calling
250// WebPDataClear().
251// nth=0 has a special meaning - last position.
252// Parameters:
253// mux - (in) object from which the info is to be fetched
254// nth - (in) index of the frame in the mux object
255// frame - (out) data of the returned frame
256// Returns:
257// WEBP_MUX_INVALID_ARGUMENT - if mux or frame is NULL.
258// WEBP_MUX_NOT_FOUND - if there are less than nth frames in the mux object.
259// WEBP_MUX_BAD_DATA - if nth frame chunk in mux is invalid.
260// WEBP_MUX_MEMORY_ERROR - on memory allocation error.
261// WEBP_MUX_OK - on success.
262WEBP_EXTERN WebPMuxError WebPMuxGetFrame(
263 const WebPMux* mux, uint32_t nth, WebPMuxFrameInfo* frame);
264
265// Deletes a frame from the mux object.
266// nth=0 has a special meaning - last position.
267// Parameters:
268// mux - (in/out) object from which a frame is to be deleted
269// nth - (in) The position from which the frame is to be deleted
270// Returns:
271// WEBP_MUX_INVALID_ARGUMENT - if mux is NULL.
272// WEBP_MUX_NOT_FOUND - If there are less than nth frames in the mux object
273// before deletion.
274// WEBP_MUX_OK - on success.
275WEBP_EXTERN WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
276
277//------------------------------------------------------------------------------
278// Animation.
279
280// Animation parameters.
281struct WebPMuxAnimParams {
282 uint32_t bgcolor; // Background color of the canvas stored (in MSB order) as:
283 // Bits 00 to 07: Alpha.
284 // Bits 08 to 15: Red.
285 // Bits 16 to 23: Green.
286 // Bits 24 to 31: Blue.
287 int loop_count; // Number of times to repeat the animation [0 = infinite].
288};
289
290// Sets the animation parameters in the mux object. Any existing ANIM chunks
291// will be removed.
292// Parameters:
293// mux - (in/out) object in which ANIM chunk is to be set/added
294// params - (in) animation parameters.
295// Returns:
296// WEBP_MUX_INVALID_ARGUMENT - if mux or params is NULL.
297// WEBP_MUX_MEMORY_ERROR - on memory allocation error.
298// WEBP_MUX_OK - on success.
299WEBP_EXTERN WebPMuxError WebPMuxSetAnimationParams(
300 WebPMux* mux, const WebPMuxAnimParams* params);
301
302// Gets the animation parameters from the mux object.
303// Parameters:
304// mux - (in) object from which the animation parameters to be fetched
305// params - (out) animation parameters extracted from the ANIM chunk
306// Returns:
307// WEBP_MUX_INVALID_ARGUMENT - if mux or params is NULL.
308// WEBP_MUX_NOT_FOUND - if ANIM chunk is not present in mux object.
309// WEBP_MUX_OK - on success.
310WEBP_EXTERN WebPMuxError WebPMuxGetAnimationParams(
311 const WebPMux* mux, WebPMuxAnimParams* params);
312
313//------------------------------------------------------------------------------
314// Misc Utilities.
315
316// Sets the canvas size for the mux object. The width and height can be
317// specified explicitly or left as zero (0, 0).
318// * When width and height are specified explicitly, then this frame bound is
319// enforced during subsequent calls to WebPMuxAssemble() and an error is
320// reported if any animated frame does not completely fit within the canvas.
321// * When unspecified (0, 0), the constructed canvas will get the frame bounds
322// from the bounding-box over all frames after calling WebPMuxAssemble().
323// Parameters:
324// mux - (in) object to which the canvas size is to be set
325// width - (in) canvas width
326// height - (in) canvas height
327// Returns:
328// WEBP_MUX_INVALID_ARGUMENT - if mux is NULL; or
329// width or height are invalid or out of bounds
330// WEBP_MUX_OK - on success.
331WEBP_EXTERN WebPMuxError WebPMuxSetCanvasSize(WebPMux* mux,
332 int width, int height);
333
334// Gets the canvas size from the mux object.
335// Note: This method assumes that the VP8X chunk, if present, is up-to-date.
336// That is, the mux object hasn't been modified since the last call to
337// WebPMuxAssemble() or WebPMuxCreate().
338// Parameters:
339// mux - (in) object from which the canvas size is to be fetched
340// width - (out) canvas width
341// height - (out) canvas height
342// Returns:
343// WEBP_MUX_INVALID_ARGUMENT - if mux, width or height is NULL.
344// WEBP_MUX_BAD_DATA - if VP8X/VP8/VP8L chunk or canvas size is invalid.
345// WEBP_MUX_OK - on success.
346WEBP_EXTERN WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux,
347 int* width, int* height);
348
349// Gets the feature flags from the mux object.
350// Note: This method assumes that the VP8X chunk, if present, is up-to-date.
351// That is, the mux object hasn't been modified since the last call to
352// WebPMuxAssemble() or WebPMuxCreate().
353// Parameters:
354// mux - (in) object from which the features are to be fetched
355// flags - (out) the flags specifying which features are present in the
356// mux object. This will be an OR of various flag values.
357// Enum 'WebPFeatureFlags' can be used to test individual flag values.
358// Returns:
359// WEBP_MUX_INVALID_ARGUMENT - if mux or flags is NULL.
360// WEBP_MUX_BAD_DATA - if VP8X/VP8/VP8L chunk or canvas size is invalid.
361// WEBP_MUX_OK - on success.
362WEBP_EXTERN WebPMuxError WebPMuxGetFeatures(const WebPMux* mux,
363 uint32_t* flags);
364
365// Gets number of chunks with the given 'id' in the mux object.
366// Parameters:
367// mux - (in) object from which the info is to be fetched
368// id - (in) chunk id specifying the type of chunk
369// num_elements - (out) number of chunks with the given chunk id
370// Returns:
371// WEBP_MUX_INVALID_ARGUMENT - if mux, or num_elements is NULL.
372// WEBP_MUX_OK - on success.
373WEBP_EXTERN WebPMuxError WebPMuxNumChunks(const WebPMux* mux,
374 WebPChunkId id, int* num_elements);
375
376// Assembles all chunks in WebP RIFF format and returns in 'assembled_data'.
377// This function also validates the mux object.
378// Note: The content of 'assembled_data' will be ignored and overwritten.
379// Also, the content of 'assembled_data' is allocated using WebPMalloc(), and
380// NOT owned by the 'mux' object. It MUST be deallocated by the caller by
381// calling WebPDataClear(). It's always safe to call WebPDataClear() upon
382// return, even in case of error.
383// Parameters:
384// mux - (in/out) object whose chunks are to be assembled
385// assembled_data - (out) assembled WebP data
386// Returns:
387// WEBP_MUX_BAD_DATA - if mux object is invalid.
388// WEBP_MUX_INVALID_ARGUMENT - if mux or assembled_data is NULL.
389// WEBP_MUX_MEMORY_ERROR - on memory allocation error.
390// WEBP_MUX_OK - on success.
391WEBP_EXTERN WebPMuxError WebPMuxAssemble(WebPMux* mux,
392 WebPData* assembled_data);
393
394//------------------------------------------------------------------------------
395// WebPAnimEncoder API
396//
397// This API allows encoding (possibly) animated WebP images.
398//
399// Code Example:
400/*
401 WebPAnimEncoderOptions enc_options;
402 WebPAnimEncoderOptionsInit(&enc_options);
403 // Tune 'enc_options' as needed.
404 WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
405 while(<there are more frames>) {
406 WebPConfig config;
407 WebPConfigInit(&config);
408 // Tune 'config' as needed.
409 WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config);
410 }
411 WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL);
412 WebPAnimEncoderAssemble(enc, webp_data);
413 WebPAnimEncoderDelete(enc);
414 // Write the 'webp_data' to a file, or re-mux it further.
415*/
416
417typedef struct WebPAnimEncoder WebPAnimEncoder; // Main opaque object.
418
419// Forward declarations. Defined in encode.h.
420struct WebPPicture;
421struct WebPConfig;
422
423// Global options.
424struct WebPAnimEncoderOptions {
425 WebPMuxAnimParams anim_params; // Animation parameters.
426 int minimize_size; // If true, minimize the output size (slow). Implicitly
427 // disables key-frame insertion.
428 int kmin;
429 int kmax; // Minimum and maximum distance between consecutive key
430 // frames in the output. The library may insert some key
431 // frames as needed to satisfy this criteria.
432 // Note that these conditions should hold: kmax > kmin
433 // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then
434 // key-frame insertion is disabled; and if kmax == 1,
435 // then all frames will be key-frames (kmin value does
436 // not matter for these special cases).
437 int allow_mixed; // If true, use mixed compression mode; may choose
438 // either lossy and lossless for each frame.
439 int verbose; // If true, print info and warning messages to stderr.
440
441 uint32_t padding[4]; // Padding for later use.
442};
443
444// Internal, version-checked, entry point.
445WEBP_EXTERN int WebPAnimEncoderOptionsInitInternal(
446 WebPAnimEncoderOptions*, int);
447
448// Should always be called, to initialize a fresh WebPAnimEncoderOptions
449// structure before modification. Returns false in case of version mismatch.
450// WebPAnimEncoderOptionsInit() must have succeeded before using the
451// 'enc_options' object.
452static WEBP_INLINE int WebPAnimEncoderOptionsInit(
453 WebPAnimEncoderOptions* enc_options) {
454 return WebPAnimEncoderOptionsInitInternal(enc_options, WEBP_MUX_ABI_VERSION);
455}
456
457// Internal, version-checked, entry point.
458WEBP_EXTERN WebPAnimEncoder* WebPAnimEncoderNewInternal(
459 int, int, const WebPAnimEncoderOptions*, int);
460
461// Creates and initializes a WebPAnimEncoder object.
462// Parameters:
463// width/height - (in) canvas width and height of the animation.
464// enc_options - (in) encoding options; can be passed NULL to pick
465// reasonable defaults.
466// Returns:
467// A pointer to the newly created WebPAnimEncoder object.
468// Or NULL in case of memory error.
469static WEBP_INLINE WebPAnimEncoder* WebPAnimEncoderNew(
470 int width, int height, const WebPAnimEncoderOptions* enc_options) {
471 return WebPAnimEncoderNewInternal(width, height, enc_options,
472 WEBP_MUX_ABI_VERSION);
473}
474
475// Optimize the given frame for WebP, encode it and add it to the
476// WebPAnimEncoder object.
477// The last call to 'WebPAnimEncoderAdd' should be with frame = NULL, which
478// indicates that no more frames are to be added. This call is also used to
479// determine the duration of the last frame.
480// Parameters:
481// enc - (in/out) object to which the frame is to be added.
482// frame - (in/out) frame data in ARGB or YUV(A) format. If it is in YUV(A)
483// format, it will be converted to ARGB, which incurs a small loss.
484// timestamp_ms - (in) timestamp of this frame in milliseconds.
485// Duration of a frame would be calculated as
486// "timestamp of next frame - timestamp of this frame".
487// Hence, timestamps should be in non-decreasing order.
488// config - (in) encoding options; can be passed NULL to pick
489// reasonable defaults.
490// Returns:
491// On error, returns false and frame->error_code is set appropriately.
492// Otherwise, returns true.
493WEBP_EXTERN int WebPAnimEncoderAdd(
494 WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms,
495 const struct WebPConfig* config);
496
497// Assemble all frames added so far into a WebP bitstream.
498// This call should be preceded by a call to 'WebPAnimEncoderAdd' with
499// frame = NULL; if not, the duration of the last frame will be internally
500// estimated.
501// Parameters:
502// enc - (in/out) object from which the frames are to be assembled.
503// webp_data - (out) generated WebP bitstream.
504// Returns:
505// True on success.
506WEBP_EXTERN int WebPAnimEncoderAssemble(WebPAnimEncoder* enc,
507 WebPData* webp_data);
508
509// Get error string corresponding to the most recent call using 'enc'. The
510// returned string is owned by 'enc' and is valid only until the next call to
511// WebPAnimEncoderAdd() or WebPAnimEncoderAssemble() or WebPAnimEncoderDelete().
512// Parameters:
513// enc - (in/out) object from which the error string is to be fetched.
514// Returns:
515// NULL if 'enc' is NULL. Otherwise, returns the error string if the last call
516// to 'enc' had an error, or an empty string if the last call was a success.
517WEBP_EXTERN const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);
518
519// Deletes the WebPAnimEncoder object.
520// Parameters:
521// enc - (in/out) object to be deleted
522WEBP_EXTERN void WebPAnimEncoderDelete(WebPAnimEncoder* enc);
523
524//------------------------------------------------------------------------------
525
526#ifdef __cplusplus
527} // extern "C"
528#endif
529
530#endif // WEBP_WEBP_MUX_H_
531