jpayne@69: // Copyright 2011 Google Inc. All Rights Reserved. jpayne@69: // jpayne@69: // Use of this source code is governed by a BSD-style license jpayne@69: // that can be found in the COPYING file in the root of the source jpayne@69: // tree. An additional intellectual property rights grant can be found jpayne@69: // in the file PATENTS. All contributing project authors may jpayne@69: // be found in the AUTHORS file in the root of the source tree. jpayne@69: // ----------------------------------------------------------------------------- jpayne@69: // jpayne@69: // RIFF container manipulation and encoding for WebP images. jpayne@69: // jpayne@69: // Authors: Urvang (urvang@google.com) jpayne@69: // Vikas (vikasa@google.com) jpayne@69: jpayne@69: #ifndef WEBP_WEBP_MUX_H_ jpayne@69: #define WEBP_WEBP_MUX_H_ jpayne@69: jpayne@69: #include "./mux_types.h" jpayne@69: #include "./types.h" jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: extern "C" { jpayne@69: #endif jpayne@69: jpayne@69: #define WEBP_MUX_ABI_VERSION 0x0109 // MAJOR(8b) + MINOR(8b) jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Mux API jpayne@69: // jpayne@69: // This API allows manipulation of WebP container images containing features jpayne@69: // like color profile, metadata, animation. jpayne@69: // jpayne@69: // Code Example#1: Create a WebPMux object with image data, color profile and jpayne@69: // XMP metadata. jpayne@69: /* jpayne@69: int copy_data = 0; jpayne@69: WebPMux* mux = WebPMuxNew(); jpayne@69: // ... (Prepare image data). jpayne@69: WebPMuxSetImage(mux, &image, copy_data); jpayne@69: // ... (Prepare ICCP color profile data). jpayne@69: WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data); jpayne@69: // ... (Prepare XMP metadata). jpayne@69: WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data); jpayne@69: // Get data from mux in WebP RIFF format. jpayne@69: WebPMuxAssemble(mux, &output_data); jpayne@69: WebPMuxDelete(mux); jpayne@69: // ... (Consume output_data; e.g. write output_data.bytes to file). jpayne@69: WebPDataClear(&output_data); jpayne@69: */ jpayne@69: jpayne@69: // Code Example#2: Get image and color profile data from a WebP file. jpayne@69: /* jpayne@69: int copy_data = 0; jpayne@69: // ... (Read data from file). jpayne@69: WebPMux* mux = WebPMuxCreate(&data, copy_data); jpayne@69: WebPMuxGetFrame(mux, 1, &image); jpayne@69: // ... (Consume image; e.g. call WebPDecode() to decode the data). jpayne@69: WebPMuxGetChunk(mux, "ICCP", &icc_profile); jpayne@69: // ... (Consume icc_data). jpayne@69: WebPMuxDelete(mux); jpayne@69: WebPFree(data); jpayne@69: */ jpayne@69: jpayne@69: // Note: forward declaring enumerations is not allowed in (strict) C and C++, jpayne@69: // the types are left here for reference. jpayne@69: // typedef enum WebPMuxError WebPMuxError; jpayne@69: // typedef enum WebPChunkId WebPChunkId; jpayne@69: typedef struct WebPMux WebPMux; // main opaque object. jpayne@69: typedef struct WebPMuxFrameInfo WebPMuxFrameInfo; jpayne@69: typedef struct WebPMuxAnimParams WebPMuxAnimParams; jpayne@69: typedef struct WebPAnimEncoderOptions WebPAnimEncoderOptions; jpayne@69: jpayne@69: // Error codes jpayne@69: typedef enum WEBP_NODISCARD WebPMuxError { jpayne@69: WEBP_MUX_OK = 1, jpayne@69: WEBP_MUX_NOT_FOUND = 0, jpayne@69: WEBP_MUX_INVALID_ARGUMENT = -1, jpayne@69: WEBP_MUX_BAD_DATA = -2, jpayne@69: WEBP_MUX_MEMORY_ERROR = -3, jpayne@69: WEBP_MUX_NOT_ENOUGH_DATA = -4 jpayne@69: } WebPMuxError; jpayne@69: jpayne@69: // IDs for different types of chunks. jpayne@69: typedef enum WebPChunkId { jpayne@69: WEBP_CHUNK_VP8X, // VP8X jpayne@69: WEBP_CHUNK_ICCP, // ICCP jpayne@69: WEBP_CHUNK_ANIM, // ANIM jpayne@69: WEBP_CHUNK_ANMF, // ANMF jpayne@69: WEBP_CHUNK_DEPRECATED, // (deprecated from FRGM) jpayne@69: WEBP_CHUNK_ALPHA, // ALPH jpayne@69: WEBP_CHUNK_IMAGE, // VP8/VP8L jpayne@69: WEBP_CHUNK_EXIF, // EXIF jpayne@69: WEBP_CHUNK_XMP, // XMP jpayne@69: WEBP_CHUNK_UNKNOWN, // Other chunks. jpayne@69: WEBP_CHUNK_NIL jpayne@69: } WebPChunkId; jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: jpayne@69: // Returns the version number of the mux library, packed in hexadecimal using jpayne@69: // 8bits for each of major/minor/revision. E.g: v2.5.7 is 0x020507. jpayne@69: WEBP_EXTERN int WebPGetMuxVersion(void); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Life of a Mux object jpayne@69: jpayne@69: // Internal, version-checked, entry point jpayne@69: WEBP_NODISCARD WEBP_EXTERN WebPMux* WebPNewInternal(int); jpayne@69: jpayne@69: // Creates an empty mux object. jpayne@69: // Returns: jpayne@69: // A pointer to the newly created empty mux object. jpayne@69: // Or NULL in case of memory error. jpayne@69: WEBP_NODISCARD static WEBP_INLINE WebPMux* WebPMuxNew(void) { jpayne@69: return WebPNewInternal(WEBP_MUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: // Deletes the mux object. jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object to be deleted jpayne@69: WEBP_EXTERN void WebPMuxDelete(WebPMux* mux); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Mux creation. jpayne@69: jpayne@69: // Internal, version-checked, entry point jpayne@69: WEBP_NODISCARD WEBP_EXTERN WebPMux* WebPMuxCreateInternal(const WebPData*, int, jpayne@69: int); jpayne@69: jpayne@69: // Creates a mux object from raw data given in WebP RIFF format. jpayne@69: // Parameters: jpayne@69: // bitstream - (in) the bitstream data in WebP RIFF format jpayne@69: // copy_data - (in) value 1 indicates given data WILL be copied to the mux jpayne@69: // object and value 0 indicates data will NOT be copied. If the jpayne@69: // data is not copied, it must exist for the lifetime of the jpayne@69: // mux object. jpayne@69: // Returns: jpayne@69: // A pointer to the mux object created from given data - on success. jpayne@69: // NULL - In case of invalid data or memory error. jpayne@69: WEBP_NODISCARD static WEBP_INLINE WebPMux* WebPMuxCreate( jpayne@69: const WebPData* bitstream, int copy_data) { jpayne@69: return WebPMuxCreateInternal(bitstream, copy_data, WEBP_MUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Non-image chunks. jpayne@69: jpayne@69: // Note: Only non-image related chunks should be managed through chunk APIs. jpayne@69: // (Image related chunks are: "ANMF", "VP8 ", "VP8L" and "ALPH"). jpayne@69: // To add, get and delete images, use WebPMuxSetImage(), WebPMuxPushFrame(), jpayne@69: // WebPMuxGetFrame() and WebPMuxDeleteFrame(). jpayne@69: jpayne@69: // Adds a chunk with id 'fourcc' and data 'chunk_data' in the mux object. jpayne@69: // Any existing chunk(s) with the same id will be removed. jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object to which the chunk is to be added jpayne@69: // fourcc - (in) a character array containing the fourcc of the given chunk; jpayne@69: // e.g., "ICCP", "XMP ", "EXIF" etc. jpayne@69: // chunk_data - (in) the chunk data to be added jpayne@69: // copy_data - (in) value 1 indicates given data WILL be copied to the mux jpayne@69: // object and value 0 indicates data will NOT be copied. If the jpayne@69: // data is not copied, it must exist until a call to jpayne@69: // WebPMuxAssemble() is made. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux, fourcc or chunk_data is NULL jpayne@69: // or if fourcc corresponds to an image chunk. jpayne@69: // WEBP_MUX_MEMORY_ERROR - on memory allocation error. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxSetChunk( jpayne@69: WebPMux* mux, const char fourcc[4], const WebPData* chunk_data, jpayne@69: int copy_data); jpayne@69: jpayne@69: // Gets a reference to the data of the chunk with id 'fourcc' in the mux object. jpayne@69: // The caller should NOT free the returned data. jpayne@69: // Parameters: jpayne@69: // mux - (in) object from which the chunk data is to be fetched jpayne@69: // fourcc - (in) a character array containing the fourcc of the chunk; jpayne@69: // e.g., "ICCP", "XMP ", "EXIF" etc. jpayne@69: // chunk_data - (out) returned chunk data jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux, fourcc or chunk_data is NULL jpayne@69: // or if fourcc corresponds to an image chunk. jpayne@69: // WEBP_MUX_NOT_FOUND - If mux does not contain a chunk with the given id. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxGetChunk( jpayne@69: const WebPMux* mux, const char fourcc[4], WebPData* chunk_data); jpayne@69: jpayne@69: // Deletes the chunk with the given 'fourcc' from the mux object. jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object from which the chunk is to be deleted jpayne@69: // fourcc - (in) a character array containing the fourcc of the chunk; jpayne@69: // e.g., "ICCP", "XMP ", "EXIF" etc. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux or fourcc is NULL jpayne@69: // or if fourcc corresponds to an image chunk. jpayne@69: // WEBP_MUX_NOT_FOUND - If mux does not contain a chunk with the given fourcc. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxDeleteChunk( jpayne@69: WebPMux* mux, const char fourcc[4]); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Images. jpayne@69: jpayne@69: // Encapsulates data about a single frame. jpayne@69: struct WebPMuxFrameInfo { jpayne@69: WebPData bitstream; // image data: can be a raw VP8/VP8L bitstream jpayne@69: // or a single-image WebP file. jpayne@69: int x_offset; // x-offset of the frame. jpayne@69: int y_offset; // y-offset of the frame. jpayne@69: int duration; // duration of the frame (in milliseconds). jpayne@69: jpayne@69: WebPChunkId id; // frame type: should be one of WEBP_CHUNK_ANMF jpayne@69: // or WEBP_CHUNK_IMAGE jpayne@69: WebPMuxAnimDispose dispose_method; // Disposal method for the frame. jpayne@69: WebPMuxAnimBlend blend_method; // Blend operation for the frame. jpayne@69: uint32_t pad[1]; // padding for later use jpayne@69: }; jpayne@69: jpayne@69: // Sets the (non-animated) image in the mux object. jpayne@69: // Note: Any existing images (including frames) will be removed. jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object in which the image is to be set jpayne@69: // bitstream - (in) can be a raw VP8/VP8L bitstream or a single-image jpayne@69: // WebP file (non-animated) jpayne@69: // copy_data - (in) value 1 indicates given data WILL be copied to the mux jpayne@69: // object and value 0 indicates data will NOT be copied. If the jpayne@69: // data is not copied, it must exist until a call to jpayne@69: // WebPMuxAssemble() is made. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux is NULL or bitstream is NULL. jpayne@69: // WEBP_MUX_MEMORY_ERROR - on memory allocation error. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxSetImage( jpayne@69: WebPMux* mux, const WebPData* bitstream, int copy_data); jpayne@69: jpayne@69: // Adds a frame at the end of the mux object. jpayne@69: // Notes: (1) frame.id should be WEBP_CHUNK_ANMF jpayne@69: // (2) For setting a non-animated image, use WebPMuxSetImage() instead. jpayne@69: // (3) Type of frame being pushed must be same as the frames in mux. jpayne@69: // (4) As WebP only supports even offsets, any odd offset will be snapped jpayne@69: // to an even location using: offset &= ~1 jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object to which the frame is to be added jpayne@69: // frame - (in) frame data. jpayne@69: // copy_data - (in) value 1 indicates given data WILL be copied to the mux jpayne@69: // object and value 0 indicates data will NOT be copied. If the jpayne@69: // data is not copied, it must exist until a call to jpayne@69: // WebPMuxAssemble() is made. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux or frame is NULL jpayne@69: // or if content of 'frame' is invalid. jpayne@69: // WEBP_MUX_MEMORY_ERROR - on memory allocation error. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxPushFrame( jpayne@69: WebPMux* mux, const WebPMuxFrameInfo* frame, int copy_data); jpayne@69: jpayne@69: // Gets the nth frame from the mux object. jpayne@69: // The content of 'frame->bitstream' is allocated using WebPMalloc(), and NOT jpayne@69: // owned by the 'mux' object. It MUST be deallocated by the caller by calling jpayne@69: // WebPDataClear(). jpayne@69: // nth=0 has a special meaning - last position. jpayne@69: // Parameters: jpayne@69: // mux - (in) object from which the info is to be fetched jpayne@69: // nth - (in) index of the frame in the mux object jpayne@69: // frame - (out) data of the returned frame jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux or frame is NULL. jpayne@69: // WEBP_MUX_NOT_FOUND - if there are less than nth frames in the mux object. jpayne@69: // WEBP_MUX_BAD_DATA - if nth frame chunk in mux is invalid. jpayne@69: // WEBP_MUX_MEMORY_ERROR - on memory allocation error. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxGetFrame( jpayne@69: const WebPMux* mux, uint32_t nth, WebPMuxFrameInfo* frame); jpayne@69: jpayne@69: // Deletes a frame from the mux object. jpayne@69: // nth=0 has a special meaning - last position. jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object from which a frame is to be deleted jpayne@69: // nth - (in) The position from which the frame is to be deleted jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux is NULL. jpayne@69: // WEBP_MUX_NOT_FOUND - If there are less than nth frames in the mux object jpayne@69: // before deletion. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Animation. jpayne@69: jpayne@69: // Animation parameters. jpayne@69: struct WebPMuxAnimParams { jpayne@69: uint32_t bgcolor; // Background color of the canvas stored (in MSB order) as: jpayne@69: // Bits 00 to 07: Alpha. jpayne@69: // Bits 08 to 15: Red. jpayne@69: // Bits 16 to 23: Green. jpayne@69: // Bits 24 to 31: Blue. jpayne@69: int loop_count; // Number of times to repeat the animation [0 = infinite]. jpayne@69: }; jpayne@69: jpayne@69: // Sets the animation parameters in the mux object. Any existing ANIM chunks jpayne@69: // will be removed. jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object in which ANIM chunk is to be set/added jpayne@69: // params - (in) animation parameters. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux or params is NULL. jpayne@69: // WEBP_MUX_MEMORY_ERROR - on memory allocation error. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxSetAnimationParams( jpayne@69: WebPMux* mux, const WebPMuxAnimParams* params); jpayne@69: jpayne@69: // Gets the animation parameters from the mux object. jpayne@69: // Parameters: jpayne@69: // mux - (in) object from which the animation parameters to be fetched jpayne@69: // params - (out) animation parameters extracted from the ANIM chunk jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux or params is NULL. jpayne@69: // WEBP_MUX_NOT_FOUND - if ANIM chunk is not present in mux object. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxGetAnimationParams( jpayne@69: const WebPMux* mux, WebPMuxAnimParams* params); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Misc Utilities. jpayne@69: jpayne@69: // Sets the canvas size for the mux object. The width and height can be jpayne@69: // specified explicitly or left as zero (0, 0). jpayne@69: // * When width and height are specified explicitly, then this frame bound is jpayne@69: // enforced during subsequent calls to WebPMuxAssemble() and an error is jpayne@69: // reported if any animated frame does not completely fit within the canvas. jpayne@69: // * When unspecified (0, 0), the constructed canvas will get the frame bounds jpayne@69: // from the bounding-box over all frames after calling WebPMuxAssemble(). jpayne@69: // Parameters: jpayne@69: // mux - (in) object to which the canvas size is to be set jpayne@69: // width - (in) canvas width jpayne@69: // height - (in) canvas height jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux is NULL; or jpayne@69: // width or height are invalid or out of bounds jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxSetCanvasSize(WebPMux* mux, jpayne@69: int width, int height); jpayne@69: jpayne@69: // Gets the canvas size from the mux object. jpayne@69: // Note: This method assumes that the VP8X chunk, if present, is up-to-date. jpayne@69: // That is, the mux object hasn't been modified since the last call to jpayne@69: // WebPMuxAssemble() or WebPMuxCreate(). jpayne@69: // Parameters: jpayne@69: // mux - (in) object from which the canvas size is to be fetched jpayne@69: // width - (out) canvas width jpayne@69: // height - (out) canvas height jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux, width or height is NULL. jpayne@69: // WEBP_MUX_BAD_DATA - if VP8X/VP8/VP8L chunk or canvas size is invalid. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux, jpayne@69: int* width, int* height); jpayne@69: jpayne@69: // Gets the feature flags from the mux object. jpayne@69: // Note: This method assumes that the VP8X chunk, if present, is up-to-date. jpayne@69: // That is, the mux object hasn't been modified since the last call to jpayne@69: // WebPMuxAssemble() or WebPMuxCreate(). jpayne@69: // Parameters: jpayne@69: // mux - (in) object from which the features are to be fetched jpayne@69: // flags - (out) the flags specifying which features are present in the jpayne@69: // mux object. This will be an OR of various flag values. jpayne@69: // Enum 'WebPFeatureFlags' can be used to test individual flag values. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux or flags is NULL. jpayne@69: // WEBP_MUX_BAD_DATA - if VP8X/VP8/VP8L chunk or canvas size is invalid. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxGetFeatures(const WebPMux* mux, jpayne@69: uint32_t* flags); jpayne@69: jpayne@69: // Gets number of chunks with the given 'id' in the mux object. jpayne@69: // Parameters: jpayne@69: // mux - (in) object from which the info is to be fetched jpayne@69: // id - (in) chunk id specifying the type of chunk jpayne@69: // num_elements - (out) number of chunks with the given chunk id jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux, or num_elements is NULL. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxNumChunks(const WebPMux* mux, jpayne@69: WebPChunkId id, int* num_elements); jpayne@69: jpayne@69: // Assembles all chunks in WebP RIFF format and returns in 'assembled_data'. jpayne@69: // This function also validates the mux object. jpayne@69: // Note: The content of 'assembled_data' will be ignored and overwritten. jpayne@69: // Also, the content of 'assembled_data' is allocated using WebPMalloc(), and jpayne@69: // NOT owned by the 'mux' object. It MUST be deallocated by the caller by jpayne@69: // calling WebPDataClear(). It's always safe to call WebPDataClear() upon jpayne@69: // return, even in case of error. jpayne@69: // Parameters: jpayne@69: // mux - (in/out) object whose chunks are to be assembled jpayne@69: // assembled_data - (out) assembled WebP data jpayne@69: // Returns: jpayne@69: // WEBP_MUX_BAD_DATA - if mux object is invalid. jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if mux or assembled_data is NULL. jpayne@69: // WEBP_MUX_MEMORY_ERROR - on memory allocation error. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPMuxAssemble(WebPMux* mux, jpayne@69: WebPData* assembled_data); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // WebPAnimEncoder API jpayne@69: // jpayne@69: // This API allows encoding (possibly) animated WebP images. jpayne@69: // jpayne@69: // Code Example: jpayne@69: /* jpayne@69: WebPAnimEncoderOptions enc_options; jpayne@69: WebPAnimEncoderOptionsInit(&enc_options); jpayne@69: // Tune 'enc_options' as needed. jpayne@69: WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options); jpayne@69: while() { jpayne@69: WebPConfig config; jpayne@69: WebPConfigInit(&config); jpayne@69: // Tune 'config' as needed. jpayne@69: WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config); jpayne@69: } jpayne@69: WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL); jpayne@69: WebPAnimEncoderAssemble(enc, webp_data); jpayne@69: WebPAnimEncoderDelete(enc); jpayne@69: // Write the 'webp_data' to a file, or re-mux it further. jpayne@69: */ jpayne@69: jpayne@69: typedef struct WebPAnimEncoder WebPAnimEncoder; // Main opaque object. jpayne@69: jpayne@69: // Forward declarations. Defined in encode.h. jpayne@69: struct WebPPicture; jpayne@69: struct WebPConfig; jpayne@69: jpayne@69: // Global options. jpayne@69: struct WebPAnimEncoderOptions { jpayne@69: WebPMuxAnimParams anim_params; // Animation parameters. jpayne@69: int minimize_size; // If true, minimize the output size (slow). Implicitly jpayne@69: // disables key-frame insertion. jpayne@69: int kmin; jpayne@69: int kmax; // Minimum and maximum distance between consecutive key jpayne@69: // frames in the output. The library may insert some key jpayne@69: // frames as needed to satisfy this criteria. jpayne@69: // Note that these conditions should hold: kmax > kmin jpayne@69: // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then jpayne@69: // key-frame insertion is disabled; and if kmax == 1, jpayne@69: // then all frames will be key-frames (kmin value does jpayne@69: // not matter for these special cases). jpayne@69: int allow_mixed; // If true, use mixed compression mode; may choose jpayne@69: // either lossy and lossless for each frame. jpayne@69: int verbose; // If true, print info and warning messages to stderr. jpayne@69: jpayne@69: uint32_t padding[4]; // Padding for later use. jpayne@69: }; jpayne@69: jpayne@69: // Internal, version-checked, entry point. jpayne@69: WEBP_EXTERN int WebPAnimEncoderOptionsInitInternal( jpayne@69: WebPAnimEncoderOptions*, int); jpayne@69: jpayne@69: // Should always be called, to initialize a fresh WebPAnimEncoderOptions jpayne@69: // structure before modification. Returns false in case of version mismatch. jpayne@69: // WebPAnimEncoderOptionsInit() must have succeeded before using the jpayne@69: // 'enc_options' object. jpayne@69: WEBP_NODISCARD static WEBP_INLINE int WebPAnimEncoderOptionsInit( jpayne@69: WebPAnimEncoderOptions* enc_options) { jpayne@69: return WebPAnimEncoderOptionsInitInternal(enc_options, WEBP_MUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: // Internal, version-checked, entry point. jpayne@69: WEBP_EXTERN WebPAnimEncoder* WebPAnimEncoderNewInternal( jpayne@69: int, int, const WebPAnimEncoderOptions*, int); jpayne@69: jpayne@69: // Creates and initializes a WebPAnimEncoder object. jpayne@69: // Parameters: jpayne@69: // width/height - (in) canvas width and height of the animation. jpayne@69: // enc_options - (in) encoding options; can be passed NULL to pick jpayne@69: // reasonable defaults. jpayne@69: // Returns: jpayne@69: // A pointer to the newly created WebPAnimEncoder object. jpayne@69: // Or NULL in case of memory error. jpayne@69: static WEBP_INLINE WebPAnimEncoder* WebPAnimEncoderNew( jpayne@69: int width, int height, const WebPAnimEncoderOptions* enc_options) { jpayne@69: return WebPAnimEncoderNewInternal(width, height, enc_options, jpayne@69: WEBP_MUX_ABI_VERSION); jpayne@69: } jpayne@69: jpayne@69: // Optimize the given frame for WebP, encode it and add it to the jpayne@69: // WebPAnimEncoder object. jpayne@69: // The last call to 'WebPAnimEncoderAdd' should be with frame = NULL, which jpayne@69: // indicates that no more frames are to be added. This call is also used to jpayne@69: // determine the duration of the last frame. jpayne@69: // Parameters: jpayne@69: // enc - (in/out) object to which the frame is to be added. jpayne@69: // frame - (in/out) frame data in ARGB or YUV(A) format. If it is in YUV(A) jpayne@69: // format, it will be converted to ARGB, which incurs a small loss. jpayne@69: // timestamp_ms - (in) timestamp of this frame in milliseconds. jpayne@69: // Duration of a frame would be calculated as jpayne@69: // "timestamp of next frame - timestamp of this frame". jpayne@69: // Hence, timestamps should be in non-decreasing order. jpayne@69: // config - (in) encoding options; can be passed NULL to pick jpayne@69: // reasonable defaults. jpayne@69: // Returns: jpayne@69: // On error, returns false and frame->error_code is set appropriately. jpayne@69: // Otherwise, returns true. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPAnimEncoderAdd( jpayne@69: WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms, jpayne@69: const struct WebPConfig* config); jpayne@69: jpayne@69: // Assemble all frames added so far into a WebP bitstream. jpayne@69: // This call should be preceded by a call to 'WebPAnimEncoderAdd' with jpayne@69: // frame = NULL; if not, the duration of the last frame will be internally jpayne@69: // estimated. jpayne@69: // Parameters: jpayne@69: // enc - (in/out) object from which the frames are to be assembled. jpayne@69: // webp_data - (out) generated WebP bitstream. jpayne@69: // Returns: jpayne@69: // True on success. jpayne@69: WEBP_NODISCARD WEBP_EXTERN int WebPAnimEncoderAssemble(WebPAnimEncoder* enc, jpayne@69: WebPData* webp_data); jpayne@69: jpayne@69: // Get error string corresponding to the most recent call using 'enc'. The jpayne@69: // returned string is owned by 'enc' and is valid only until the next call to jpayne@69: // WebPAnimEncoderAdd() or WebPAnimEncoderAssemble() or WebPAnimEncoderDelete(). jpayne@69: // Parameters: jpayne@69: // enc - (in/out) object from which the error string is to be fetched. jpayne@69: // Returns: jpayne@69: // NULL if 'enc' is NULL. Otherwise, returns the error string if the last call jpayne@69: // to 'enc' had an error, or an empty string if the last call was a success. jpayne@69: WEBP_EXTERN const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc); jpayne@69: jpayne@69: // Deletes the WebPAnimEncoder object. jpayne@69: // Parameters: jpayne@69: // enc - (in/out) object to be deleted jpayne@69: WEBP_EXTERN void WebPAnimEncoderDelete(WebPAnimEncoder* enc); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: // Non-image chunks. jpayne@69: jpayne@69: // Note: Only non-image related chunks should be managed through chunk APIs. jpayne@69: // (Image related chunks are: "ANMF", "VP8 ", "VP8L" and "ALPH"). jpayne@69: jpayne@69: // Adds a chunk with id 'fourcc' and data 'chunk_data' in the enc object. jpayne@69: // Any existing chunk(s) with the same id will be removed. jpayne@69: // Parameters: jpayne@69: // enc - (in/out) object to which the chunk is to be added jpayne@69: // fourcc - (in) a character array containing the fourcc of the given chunk; jpayne@69: // e.g., "ICCP", "XMP ", "EXIF", etc. jpayne@69: // chunk_data - (in) the chunk data to be added jpayne@69: // copy_data - (in) value 1 indicates given data WILL be copied to the enc jpayne@69: // object and value 0 indicates data will NOT be copied. If the jpayne@69: // data is not copied, it must exist until a call to jpayne@69: // WebPAnimEncoderAssemble() is made. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if enc, fourcc or chunk_data is NULL. jpayne@69: // WEBP_MUX_MEMORY_ERROR - on memory allocation error. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPAnimEncoderSetChunk( jpayne@69: WebPAnimEncoder* enc, const char fourcc[4], const WebPData* chunk_data, jpayne@69: int copy_data); jpayne@69: jpayne@69: // Gets a reference to the data of the chunk with id 'fourcc' in the enc object. jpayne@69: // The caller should NOT free the returned data. jpayne@69: // Parameters: jpayne@69: // enc - (in) object from which the chunk data is to be fetched jpayne@69: // fourcc - (in) a character array containing the fourcc of the chunk; jpayne@69: // e.g., "ICCP", "XMP ", "EXIF", etc. jpayne@69: // chunk_data - (out) returned chunk data jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if enc, fourcc or chunk_data is NULL. jpayne@69: // WEBP_MUX_NOT_FOUND - If enc does not contain a chunk with the given id. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPAnimEncoderGetChunk( jpayne@69: const WebPAnimEncoder* enc, const char fourcc[4], WebPData* chunk_data); jpayne@69: jpayne@69: // Deletes the chunk with the given 'fourcc' from the enc object. jpayne@69: // Parameters: jpayne@69: // enc - (in/out) object from which the chunk is to be deleted jpayne@69: // fourcc - (in) a character array containing the fourcc of the chunk; jpayne@69: // e.g., "ICCP", "XMP ", "EXIF", etc. jpayne@69: // Returns: jpayne@69: // WEBP_MUX_INVALID_ARGUMENT - if enc or fourcc is NULL. jpayne@69: // WEBP_MUX_NOT_FOUND - If enc does not contain a chunk with the given fourcc. jpayne@69: // WEBP_MUX_OK - on success. jpayne@69: WEBP_EXTERN WebPMuxError WebPAnimEncoderDeleteChunk( jpayne@69: WebPAnimEncoder* enc, const char fourcc[4]); jpayne@69: jpayne@69: //------------------------------------------------------------------------------ jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: } // extern "C" jpayne@69: #endif jpayne@69: jpayne@69: #endif // WEBP_WEBP_MUX_H_