· 5 years ago · Feb 03, 2021, 07:48 PM
1
2//------------------------------------------------------------------------------
3// WebPAnimEncoder API
4//
5// This API allows encoding (possibly) animated WebP images.
6//
7// Code Example:
8/*
9 WebPAnimEncoderOptions enc_options;
10 WebPAnimEncoderOptionsInit(&enc_options);
11 // Tune 'enc_options' as needed.
12 WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
13 while(<there are more frames>) {
14 WebPConfig config;
15 WebPConfigInit(&config);
16 // Tune 'config' as needed.
17 WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config);
18 }
19 WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL);
20 WebPAnimEncoderAssemble(enc, webp_data);
21 WebPAnimEncoderDelete(enc);
22 // Write the 'webp_data' to a file, or re-mux it further.
23*/
24
25typedef struct WebPAnimEncoder WebPAnimEncoder; // Main opaque object.
26
27// Forward declarations. Defined in encode.h.
28struct WebPPicture;
29struct WebPConfig;
30
31// Global options.
32struct WebPAnimEncoderOptions {
33 WebPMuxAnimParams anim_params; // Animation parameters.
34 int minimize_size; // If true, minimize the output size (slow). Implicitly
35 // disables key-frame insertion.
36 int kmin;
37 int kmax; // Minimum and maximum distance between consecutive key
38 // frames in the output. The library may insert some key
39 // frames as needed to satisfy this criteria.
40 // Note that these conditions should hold: kmax > kmin
41 // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then
42 // key-frame insertion is disabled; and if kmax == 1,
43 // then all frames will be key-frames (kmin value does
44 // not matter for these special cases).
45 int allow_mixed; // If true, use mixed compression mode; may choose
46 // either lossy and lossless for each frame.
47 int verbose; // If true, print info and warning messages to stderr.
48
49 uint32_t padding[4]; // Padding for later use.
50};
51
52// Internal, version-checked, entry point.
53WEBP_EXTERN int WebPAnimEncoderOptionsInitInternal(
54 WebPAnimEncoderOptions*, int);
55
56// Should always be called, to initialize a fresh WebPAnimEncoderOptions
57// structure before modification. Returns false in case of version mismatch.
58// WebPAnimEncoderOptionsInit() must have succeeded before using the
59// 'enc_options' object.
60static WEBP_INLINE int WebPAnimEncoderOptionsInit(
61 WebPAnimEncoderOptions* enc_options) {
62 return WebPAnimEncoderOptionsInitInternal(enc_options, WEBP_MUX_ABI_VERSION);
63}
64
65// Internal, version-checked, entry point.
66WEBP_EXTERN WebPAnimEncoder* WebPAnimEncoderNewInternal(
67 int, int, const WebPAnimEncoderOptions*, int);
68
69// Creates and initializes a WebPAnimEncoder object.
70// Parameters:
71// width/height - (in) canvas width and height of the animation.
72// enc_options - (in) encoding options; can be passed NULL to pick
73// reasonable defaults.
74// Returns:
75// A pointer to the newly created WebPAnimEncoder object.
76// Or NULL in case of memory error.
77static WEBP_INLINE WebPAnimEncoder* WebPAnimEncoderNew(
78 int width, int height, const WebPAnimEncoderOptions* enc_options) {
79 return WebPAnimEncoderNewInternal(width, height, enc_options,
80 WEBP_MUX_ABI_VERSION);
81}
82
83// Optimize the given frame for WebP, encode it and add it to the
84// WebPAnimEncoder object.
85// The last call to 'WebPAnimEncoderAdd' should be with frame = NULL, which
86// indicates that no more frames are to be added. This call is also used to
87// determine the duration of the last frame.
88// Parameters:
89// enc - (in/out) object to which the frame is to be added.
90// frame - (in/out) frame data in ARGB or YUV(A) format. If it is in YUV(A)
91// format, it will be converted to ARGB, which incurs a small loss.
92// timestamp_ms - (in) timestamp of this frame in milliseconds.
93// Duration of a frame would be calculated as
94// "timestamp of next frame - timestamp of this frame".
95// Hence, timestamps should be in non-decreasing order.
96// config - (in) encoding options; can be passed NULL to pick
97// reasonable defaults.
98// Returns:
99// On error, returns false and frame->error_code is set appropriately.
100// Otherwise, returns true.
101WEBP_EXTERN int WebPAnimEncoderAdd(
102 WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms,
103 const struct WebPConfig* config);
104
105// Assemble all frames added so far into a WebP bitstream.
106// This call should be preceded by a call to 'WebPAnimEncoderAdd' with
107// frame = NULL; if not, the duration of the last frame will be internally
108// estimated.
109// Parameters:
110// enc - (in/out) object from which the frames are to be assembled.
111// webp_data - (out) generated WebP bitstream.
112// Returns:
113// True on success.
114WEBP_EXTERN int WebPAnimEncoderAssemble(WebPAnimEncoder* enc,
115 WebPData* webp_data);
116
117// Get error string corresponding to the most recent call using 'enc'. The
118// returned string is owned by 'enc' and is valid only until the next call to
119// WebPAnimEncoderAdd() or WebPAnimEncoderAssemble() or WebPAnimEncoderDelete().
120// Parameters:
121// enc - (in/out) object from which the error string is to be fetched.
122// Returns:
123// NULL if 'enc' is NULL. Otherwise, returns the error string if the last call
124// to 'enc' had an error, or an empty string if the last call was a success.
125WEBP_EXTERN const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);
126
127// Deletes the WebPAnimEncoder object.
128// Parameters:
129// enc - (in/out) object to be deleted
130WEBP_EXTERN void WebPAnimEncoderDelete(WebPAnimEncoder* enc);
131
132//------------------------------------------------------------------------------