Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
1 | pmbaty | 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 | // WebP encoder: main interface |
||
11 | // |
||
12 | // Author: Skal (pascal.massimino@gmail.com) |
||
13 | |||
14 | #ifndef WEBP_WEBP_ENCODE_H_ |
||
15 | #define WEBP_WEBP_ENCODE_H_ |
||
16 | |||
17 | #include "./types.h" |
||
18 | |||
19 | #ifdef __cplusplus |
||
20 | extern "C" { |
||
21 | #endif |
||
22 | |||
23 | #define WEBP_ENCODER_ABI_VERSION 0x020e // MAJOR(8b) + MINOR(8b) |
||
24 | |||
25 | // Note: forward declaring enumerations is not allowed in (strict) C and C++, |
||
26 | // the types are left here for reference. |
||
27 | // typedef enum WebPImageHint WebPImageHint; |
||
28 | // typedef enum WebPEncCSP WebPEncCSP; |
||
29 | // typedef enum WebPPreset WebPPreset; |
||
30 | // typedef enum WebPEncodingError WebPEncodingError; |
||
31 | typedef struct WebPConfig WebPConfig; |
||
32 | typedef struct WebPPicture WebPPicture; // main structure for I/O |
||
33 | typedef struct WebPAuxStats WebPAuxStats; |
||
34 | typedef struct WebPMemoryWriter WebPMemoryWriter; |
||
35 | |||
36 | // Return the encoder's version number, packed in hexadecimal using 8bits for |
||
37 | // each of major/minor/revision. E.g: v2.5.7 is 0x020507. |
||
38 | WEBP_EXTERN(int) WebPGetEncoderVersion(void); |
||
39 | |||
40 | //------------------------------------------------------------------------------ |
||
41 | // One-stop-shop call! No questions asked: |
||
42 | |||
43 | // Returns the size of the compressed data (pointed to by *output), or 0 if |
||
44 | // an error occurred. The compressed data must be released by the caller |
||
45 | // using the call 'WebPFree(*output)'. |
||
46 | // These functions compress using the lossy format, and the quality_factor |
||
47 | // can go from 0 (smaller output, lower quality) to 100 (best quality, |
||
48 | // larger output). |
||
49 | WEBP_EXTERN(size_t) WebPEncodeRGB(const uint8_t* rgb, |
||
50 | int width, int height, int stride, |
||
51 | float quality_factor, uint8_t** output); |
||
52 | WEBP_EXTERN(size_t) WebPEncodeBGR(const uint8_t* bgr, |
||
53 | int width, int height, int stride, |
||
54 | float quality_factor, uint8_t** output); |
||
55 | WEBP_EXTERN(size_t) WebPEncodeRGBA(const uint8_t* rgba, |
||
56 | int width, int height, int stride, |
||
57 | float quality_factor, uint8_t** output); |
||
58 | WEBP_EXTERN(size_t) WebPEncodeBGRA(const uint8_t* bgra, |
||
59 | int width, int height, int stride, |
||
60 | float quality_factor, uint8_t** output); |
||
61 | |||
62 | // These functions are the equivalent of the above, but compressing in a |
||
63 | // lossless manner. Files are usually larger than lossy format, but will |
||
64 | // not suffer any compression loss. |
||
65 | WEBP_EXTERN(size_t) WebPEncodeLosslessRGB(const uint8_t* rgb, |
||
66 | int width, int height, int stride, |
||
67 | uint8_t** output); |
||
68 | WEBP_EXTERN(size_t) WebPEncodeLosslessBGR(const uint8_t* bgr, |
||
69 | int width, int height, int stride, |
||
70 | uint8_t** output); |
||
71 | WEBP_EXTERN(size_t) WebPEncodeLosslessRGBA(const uint8_t* rgba, |
||
72 | int width, int height, int stride, |
||
73 | uint8_t** output); |
||
74 | WEBP_EXTERN(size_t) WebPEncodeLosslessBGRA(const uint8_t* bgra, |
||
75 | int width, int height, int stride, |
||
76 | uint8_t** output); |
||
77 | |||
78 | // Releases memory returned by the WebPEncode*() functions above. |
||
79 | WEBP_EXTERN(void) WebPFree(void* ptr); |
||
80 | |||
81 | //------------------------------------------------------------------------------ |
||
82 | // Coding parameters |
||
83 | |||
84 | // Image characteristics hint for the underlying encoder. |
||
85 | typedef enum WebPImageHint { |
||
86 | WEBP_HINT_DEFAULT = 0, // default preset. |
||
87 | WEBP_HINT_PICTURE, // digital picture, like portrait, inner shot |
||
88 | WEBP_HINT_PHOTO, // outdoor photograph, with natural lighting |
||
89 | WEBP_HINT_GRAPH, // Discrete tone image (graph, map-tile etc). |
||
90 | WEBP_HINT_LAST |
||
91 | } WebPImageHint; |
||
92 | |||
93 | // Compression parameters. |
||
94 | struct WebPConfig { |
||
95 | int lossless; // Lossless encoding (0=lossy(default), 1=lossless). |
||
96 | float quality; // between 0 (smallest file) and 100 (biggest) |
||
97 | int method; // quality/speed trade-off (0=fast, 6=slower-better) |
||
98 | |||
99 | WebPImageHint image_hint; // Hint for image type (lossless only for now). |
||
100 | |||
101 | // Parameters related to lossy compression only: |
||
102 | int target_size; // if non-zero, set the desired target size in bytes. |
||
103 | // Takes precedence over the 'compression' parameter. |
||
104 | float target_PSNR; // if non-zero, specifies the minimal distortion to |
||
105 | // try to achieve. Takes precedence over target_size. |
||
106 | int segments; // maximum number of segments to use, in [1..4] |
||
107 | int sns_strength; // Spatial Noise Shaping. 0=off, 100=maximum. |
||
108 | int filter_strength; // range: [0 = off .. 100 = strongest] |
||
109 | int filter_sharpness; // range: [0 = off .. 7 = least sharp] |
||
110 | int filter_type; // filtering type: 0 = simple, 1 = strong (only used |
||
111 | // if filter_strength > 0 or autofilter > 0) |
||
112 | int autofilter; // Auto adjust filter's strength [0 = off, 1 = on] |
||
113 | int alpha_compression; // Algorithm for encoding the alpha plane (0 = none, |
||
114 | // 1 = compressed with WebP lossless). Default is 1. |
||
115 | int alpha_filtering; // Predictive filtering method for alpha plane. |
||
116 | // 0: none, 1: fast, 2: best. Default if 1. |
||
117 | int alpha_quality; // Between 0 (smallest size) and 100 (lossless). |
||
118 | // Default is 100. |
||
119 | int pass; // number of entropy-analysis passes (in [1..10]). |
||
120 | |||
121 | int show_compressed; // if true, export the compressed picture back. |
||
122 | // In-loop filtering is not applied. |
||
123 | int preprocessing; // preprocessing filter: |
||
124 | // 0=none, 1=segment-smooth, 2=pseudo-random dithering |
||
125 | int partitions; // log2(number of token partitions) in [0..3]. Default |
||
126 | // is set to 0 for easier progressive decoding. |
||
127 | int partition_limit; // quality degradation allowed to fit the 512k limit |
||
128 | // on prediction modes coding (0: no degradation, |
||
129 | // 100: maximum possible degradation). |
||
130 | int emulate_jpeg_size; // If true, compression parameters will be remapped |
||
131 | // to better match the expected output size from |
||
132 | // JPEG compression. Generally, the output size will |
||
133 | // be similar but the degradation will be lower. |
||
134 | int thread_level; // If non-zero, try and use multi-threaded encoding. |
||
135 | int low_memory; // If set, reduce memory usage (but increase CPU use). |
||
136 | |||
137 | int near_lossless; // Near lossless encoding [0 = max loss .. 100 = off |
||
138 | // (default)]. |
||
139 | int exact; // if non-zero, preserve the exact RGB values under |
||
140 | // transparent area. Otherwise, discard this invisible |
||
141 | // RGB information for better compression. The default |
||
142 | // value is 0. |
||
143 | |||
144 | int use_delta_palette; // reserved for future lossless feature |
||
145 | int use_sharp_yuv; // if needed, use sharp (and slow) RGB->YUV conversion |
||
146 | |||
147 | uint32_t pad[2]; // padding for later use |
||
148 | }; |
||
149 | |||
150 | // Enumerate some predefined settings for WebPConfig, depending on the type |
||
151 | // of source picture. These presets are used when calling WebPConfigPreset(). |
||
152 | typedef enum WebPPreset { |
||
153 | WEBP_PRESET_DEFAULT = 0, // default preset. |
||
154 | WEBP_PRESET_PICTURE, // digital picture, like portrait, inner shot |
||
155 | WEBP_PRESET_PHOTO, // outdoor photograph, with natural lighting |
||
156 | WEBP_PRESET_DRAWING, // hand or line drawing, with high-contrast details |
||
157 | WEBP_PRESET_ICON, // small-sized colorful images |
||
158 | WEBP_PRESET_TEXT // text-like |
||
159 | } WebPPreset; |
||
160 | |||
161 | // Internal, version-checked, entry point |
||
162 | WEBP_EXTERN(int) WebPConfigInitInternal(WebPConfig*, WebPPreset, float, int); |
||
163 | |||
164 | // Should always be called, to initialize a fresh WebPConfig structure before |
||
165 | // modification. Returns false in case of version mismatch. WebPConfigInit() |
||
166 | // must have succeeded before using the 'config' object. |
||
167 | // Note that the default values are lossless=0 and quality=75. |
||
168 | static WEBP_INLINE int WebPConfigInit(WebPConfig* config) { |
||
169 | return WebPConfigInitInternal(config, WEBP_PRESET_DEFAULT, 75.f, |
||
170 | WEBP_ENCODER_ABI_VERSION); |
||
171 | } |
||
172 | |||
173 | // This function will initialize the configuration according to a predefined |
||
174 | // set of parameters (referred to by 'preset') and a given quality factor. |
||
175 | // This function can be called as a replacement to WebPConfigInit(). Will |
||
176 | // return false in case of error. |
||
177 | static WEBP_INLINE int WebPConfigPreset(WebPConfig* config, |
||
178 | WebPPreset preset, float quality) { |
||
179 | return WebPConfigInitInternal(config, preset, quality, |
||
180 | WEBP_ENCODER_ABI_VERSION); |
||
181 | } |
||
182 | |||
183 | // Activate the lossless compression mode with the desired efficiency level |
||
184 | // between 0 (fastest, lowest compression) and 9 (slower, best compression). |
||
185 | // A good default level is '6', providing a fair tradeoff between compression |
||
186 | // speed and final compressed size. |
||
187 | // This function will overwrite several fields from config: 'method', 'quality' |
||
188 | // and 'lossless'. Returns false in case of parameter error. |
||
189 | WEBP_EXTERN(int) WebPConfigLosslessPreset(WebPConfig* config, int level); |
||
190 | |||
191 | // Returns true if 'config' is non-NULL and all configuration parameters are |
||
192 | // within their valid ranges. |
||
193 | WEBP_EXTERN(int) WebPValidateConfig(const WebPConfig* config); |
||
194 | |||
195 | //------------------------------------------------------------------------------ |
||
196 | // Input / Output |
||
197 | // Structure for storing auxiliary statistics (mostly for lossy encoding). |
||
198 | |||
199 | struct WebPAuxStats { |
||
200 | int coded_size; // final size |
||
201 | |||
202 | float PSNR[5]; // peak-signal-to-noise ratio for Y/U/V/All/Alpha |
||
203 | int block_count[3]; // number of intra4/intra16/skipped macroblocks |
||
204 | int header_bytes[2]; // approximate number of bytes spent for header |
||
205 | // and mode-partition #0 |
||
206 | int residual_bytes[3][4]; // approximate number of bytes spent for |
||
207 | // DC/AC/uv coefficients for each (0..3) segments. |
||
208 | int segment_size[4]; // number of macroblocks in each segments |
||
209 | int segment_quant[4]; // quantizer values for each segments |
||
210 | int segment_level[4]; // filtering strength for each segments [0..63] |
||
211 | |||
212 | int alpha_data_size; // size of the transparency data |
||
213 | int layer_data_size; // size of the enhancement layer data |
||
214 | |||
215 | // lossless encoder statistics |
||
216 | uint32_t lossless_features; // bit0:predictor bit1:cross-color transform |
||
217 | // bit2:subtract-green bit3:color indexing |
||
218 | int histogram_bits; // number of precision bits of histogram |
||
219 | int transform_bits; // precision bits for transform |
||
220 | int cache_bits; // number of bits for color cache lookup |
||
221 | int palette_size; // number of color in palette, if used |
||
222 | int lossless_size; // final lossless size |
||
223 | int lossless_hdr_size; // lossless header (transform, huffman etc) size |
||
224 | int lossless_data_size; // lossless image data size |
||
225 | |||
226 | uint32_t pad[2]; // padding for later use |
||
227 | }; |
||
228 | |||
229 | // Signature for output function. Should return true if writing was successful. |
||
230 | // data/data_size is the segment of data to write, and 'picture' is for |
||
231 | // reference (and so one can make use of picture->custom_ptr). |
||
232 | typedef int (*WebPWriterFunction)(const uint8_t* data, size_t data_size, |
||
233 | const WebPPicture* picture); |
||
234 | |||
235 | // WebPMemoryWrite: a special WebPWriterFunction that writes to memory using |
||
236 | // the following WebPMemoryWriter object (to be set as a custom_ptr). |
||
237 | struct WebPMemoryWriter { |
||
238 | uint8_t* mem; // final buffer (of size 'max_size', larger than 'size'). |
||
239 | size_t size; // final size |
||
240 | size_t max_size; // total capacity |
||
241 | uint32_t pad[1]; // padding for later use |
||
242 | }; |
||
243 | |||
244 | // The following must be called first before any use. |
||
245 | WEBP_EXTERN(void) WebPMemoryWriterInit(WebPMemoryWriter* writer); |
||
246 | |||
247 | // The following must be called to deallocate writer->mem memory. The 'writer' |
||
248 | // object itself is not deallocated. |
||
249 | WEBP_EXTERN(void) WebPMemoryWriterClear(WebPMemoryWriter* writer); |
||
250 | // The custom writer to be used with WebPMemoryWriter as custom_ptr. Upon |
||
251 | // completion, writer.mem and writer.size will hold the coded data. |
||
252 | // writer.mem must be freed by calling WebPMemoryWriterClear. |
||
253 | WEBP_EXTERN(int) WebPMemoryWrite(const uint8_t* data, size_t data_size, |
||
254 | const WebPPicture* picture); |
||
255 | |||
256 | // Progress hook, called from time to time to report progress. It can return |
||
257 | // false to request an abort of the encoding process, or true otherwise if |
||
258 | // everything is OK. |
||
259 | typedef int (*WebPProgressHook)(int percent, const WebPPicture* picture); |
||
260 | |||
261 | // Color spaces. |
||
262 | typedef enum WebPEncCSP { |
||
263 | // chroma sampling |
||
264 | WEBP_YUV420 = 0, // 4:2:0 |
||
265 | WEBP_YUV420A = 4, // alpha channel variant |
||
266 | WEBP_CSP_UV_MASK = 3, // bit-mask to get the UV sampling factors |
||
267 | WEBP_CSP_ALPHA_BIT = 4 // bit that is set if alpha is present |
||
268 | } WebPEncCSP; |
||
269 | |||
270 | // Encoding error conditions. |
||
271 | typedef enum WebPEncodingError { |
||
272 | VP8_ENC_OK = 0, |
||
273 | VP8_ENC_ERROR_OUT_OF_MEMORY, // memory error allocating objects |
||
274 | VP8_ENC_ERROR_BITSTREAM_OUT_OF_MEMORY, // memory error while flushing bits |
||
275 | VP8_ENC_ERROR_NULL_PARAMETER, // a pointer parameter is NULL |
||
276 | VP8_ENC_ERROR_INVALID_CONFIGURATION, // configuration is invalid |
||
277 | VP8_ENC_ERROR_BAD_DIMENSION, // picture has invalid width/height |
||
278 | VP8_ENC_ERROR_PARTITION0_OVERFLOW, // partition is bigger than 512k |
||
279 | VP8_ENC_ERROR_PARTITION_OVERFLOW, // partition is bigger than 16M |
||
280 | VP8_ENC_ERROR_BAD_WRITE, // error while flushing bytes |
||
281 | VP8_ENC_ERROR_FILE_TOO_BIG, // file is bigger than 4G |
||
282 | VP8_ENC_ERROR_USER_ABORT, // abort request by user |
||
283 | VP8_ENC_ERROR_LAST // list terminator. always last. |
||
284 | } WebPEncodingError; |
||
285 | |||
286 | // maximum width/height allowed (inclusive), in pixels |
||
287 | #define WEBP_MAX_DIMENSION 16383 |
||
288 | |||
289 | // Main exchange structure (input samples, output bytes, statistics) |
||
290 | struct WebPPicture { |
||
291 | // INPUT |
||
292 | ////////////// |
||
293 | // Main flag for encoder selecting between ARGB or YUV input. |
||
294 | // It is recommended to use ARGB input (*argb, argb_stride) for lossless |
||
295 | // compression, and YUV input (*y, *u, *v, etc.) for lossy compression |
||
296 | // since these are the respective native colorspace for these formats. |
||
297 | int use_argb; |
||
298 | |||
299 | // YUV input (mostly used for input to lossy compression) |
||
300 | WebPEncCSP colorspace; // colorspace: should be YUV420 for now (=Y'CbCr). |
||
301 | int width, height; // dimensions (less or equal to WEBP_MAX_DIMENSION) |
||
302 | uint8_t *y, *u, *v; // pointers to luma/chroma planes. |
||
303 | int y_stride, uv_stride; // luma/chroma strides. |
||
304 | uint8_t* a; // pointer to the alpha plane |
||
305 | int a_stride; // stride of the alpha plane |
||
306 | uint32_t pad1[2]; // padding for later use |
||
307 | |||
308 | // ARGB input (mostly used for input to lossless compression) |
||
309 | uint32_t* argb; // Pointer to argb (32 bit) plane. |
||
310 | int argb_stride; // This is stride in pixels units, not bytes. |
||
311 | uint32_t pad2[3]; // padding for later use |
||
312 | |||
313 | // OUTPUT |
||
314 | /////////////// |
||
315 | // Byte-emission hook, to store compressed bytes as they are ready. |
||
316 | WebPWriterFunction writer; // can be NULL |
||
317 | void* custom_ptr; // can be used by the writer. |
||
318 | |||
319 | // map for extra information (only for lossy compression mode) |
||
320 | int extra_info_type; // 1: intra type, 2: segment, 3: quant |
||
321 | // 4: intra-16 prediction mode, |
||
322 | // 5: chroma prediction mode, |
||
323 | // 6: bit cost, 7: distortion |
||
324 | uint8_t* extra_info; // if not NULL, points to an array of size |
||
325 | // ((width + 15) / 16) * ((height + 15) / 16) that |
||
326 | // will be filled with a macroblock map, depending |
||
327 | // on extra_info_type. |
||
328 | |||
329 | // STATS AND REPORTS |
||
330 | /////////////////////////// |
||
331 | // Pointer to side statistics (updated only if not NULL) |
||
332 | WebPAuxStats* stats; |
||
333 | |||
334 | // Error code for the latest error encountered during encoding |
||
335 | WebPEncodingError error_code; |
||
336 | |||
337 | // If not NULL, report progress during encoding. |
||
338 | WebPProgressHook progress_hook; |
||
339 | |||
340 | void* user_data; // this field is free to be set to any value and |
||
341 | // used during callbacks (like progress-report e.g.). |
||
342 | |||
343 | uint32_t pad3[3]; // padding for later use |
||
344 | |||
345 | // Unused for now |
||
346 | uint8_t *pad4, *pad5; |
||
347 | uint32_t pad6[8]; // padding for later use |
||
348 | |||
349 | // PRIVATE FIELDS |
||
350 | //////////////////// |
||
351 | void* memory_; // row chunk of memory for yuva planes |
||
352 | void* memory_argb_; // and for argb too. |
||
353 | void* pad7[2]; // padding for later use |
||
354 | }; |
||
355 | |||
356 | // Internal, version-checked, entry point |
||
357 | WEBP_EXTERN(int) WebPPictureInitInternal(WebPPicture*, int); |
||
358 | |||
359 | // Should always be called, to initialize the structure. Returns false in case |
||
360 | // of version mismatch. WebPPictureInit() must have succeeded before using the |
||
361 | // 'picture' object. |
||
362 | // Note that, by default, use_argb is false and colorspace is WEBP_YUV420. |
||
363 | static WEBP_INLINE int WebPPictureInit(WebPPicture* picture) { |
||
364 | return WebPPictureInitInternal(picture, WEBP_ENCODER_ABI_VERSION); |
||
365 | } |
||
366 | |||
367 | //------------------------------------------------------------------------------ |
||
368 | // WebPPicture utils |
||
369 | |||
370 | // Convenience allocation / deallocation based on picture->width/height: |
||
371 | // Allocate y/u/v buffers as per colorspace/width/height specification. |
||
372 | // Note! This function will free the previous buffer if needed. |
||
373 | // Returns false in case of memory error. |
||
374 | WEBP_EXTERN(int) WebPPictureAlloc(WebPPicture* picture); |
||
375 | |||
376 | // Release the memory allocated by WebPPictureAlloc() or WebPPictureImport*(). |
||
377 | // Note that this function does _not_ free the memory used by the 'picture' |
||
378 | // object itself. |
||
379 | // Besides memory (which is reclaimed) all other fields of 'picture' are |
||
380 | // preserved. |
||
381 | WEBP_EXTERN(void) WebPPictureFree(WebPPicture* picture); |
||
382 | |||
383 | // Copy the pixels of *src into *dst, using WebPPictureAlloc. Upon return, *dst |
||
384 | // will fully own the copied pixels (this is not a view). The 'dst' picture need |
||
385 | // not be initialized as its content is overwritten. |
||
386 | // Returns false in case of memory allocation error. |
||
387 | WEBP_EXTERN(int) WebPPictureCopy(const WebPPicture* src, WebPPicture* dst); |
||
388 | |||
389 | // Compute the single distortion for packed planes of samples. |
||
390 | // 'src' will be compared to 'ref', and the raw distortion stored into |
||
391 | // '*distortion'. The refined metric (log(MSE), log(1 - ssim),...' will be |
||
392 | // stored in '*result'. |
||
393 | // 'x_step' is the horizontal stride (in bytes) between samples. |
||
394 | // 'src/ref_stride' is the byte distance between rows. |
||
395 | // Returns false in case of error (bad parameter, memory allocation error, ...). |
||
396 | WEBP_EXTERN(int) WebPPlaneDistortion(const uint8_t* src, size_t src_stride, |
||
397 | const uint8_t* ref, size_t ref_stride, |
||
398 | int width, int height, |
||
399 | size_t x_step, |
||
400 | int type, // 0 = PSNR, 1 = SSIM, 2 = LSIM |
||
401 | float* distortion, float* result); |
||
402 | |||
403 | // Compute PSNR, SSIM or LSIM distortion metric between two pictures. Results |
||
404 | // are in dB, stored in result[] in the B/G/R/A/All order. The distortion is |
||
405 | // always performed using ARGB samples. Hence if the input is YUV(A), the |
||
406 | // picture will be internally converted to ARGB (just for the measurement). |
||
407 | // Warning: this function is rather CPU-intensive. |
||
408 | WEBP_EXTERN(int) WebPPictureDistortion( |
||
409 | const WebPPicture* src, const WebPPicture* ref, |
||
410 | int metric_type, // 0 = PSNR, 1 = SSIM, 2 = LSIM |
||
411 | float result[5]); |
||
412 | |||
413 | // self-crops a picture to the rectangle defined by top/left/width/height. |
||
414 | // Returns false in case of memory allocation error, or if the rectangle is |
||
415 | // outside of the source picture. |
||
416 | // The rectangle for the view is defined by the top-left corner pixel |
||
417 | // coordinates (left, top) as well as its width and height. This rectangle |
||
418 | // must be fully be comprised inside the 'src' source picture. If the source |
||
419 | // picture uses the YUV420 colorspace, the top and left coordinates will be |
||
420 | // snapped to even values. |
||
421 | WEBP_EXTERN(int) WebPPictureCrop(WebPPicture* picture, |
||
422 | int left, int top, int width, int height); |
||
423 | |||
424 | // Extracts a view from 'src' picture into 'dst'. The rectangle for the view |
||
425 | // is defined by the top-left corner pixel coordinates (left, top) as well |
||
426 | // as its width and height. This rectangle must be fully be comprised inside |
||
427 | // the 'src' source picture. If the source picture uses the YUV420 colorspace, |
||
428 | // the top and left coordinates will be snapped to even values. |
||
429 | // Picture 'src' must out-live 'dst' picture. Self-extraction of view is allowed |
||
430 | // ('src' equal to 'dst') as a mean of fast-cropping (but note that doing so, |
||
431 | // the original dimension will be lost). Picture 'dst' need not be initialized |
||
432 | // with WebPPictureInit() if it is different from 'src', since its content will |
||
433 | // be overwritten. |
||
434 | // Returns false in case of memory allocation error or invalid parameters. |
||
435 | WEBP_EXTERN(int) WebPPictureView(const WebPPicture* src, |
||
436 | int left, int top, int width, int height, |
||
437 | WebPPicture* dst); |
||
438 | |||
439 | // Returns true if the 'picture' is actually a view and therefore does |
||
440 | // not own the memory for pixels. |
||
441 | WEBP_EXTERN(int) WebPPictureIsView(const WebPPicture* picture); |
||
442 | |||
443 | // Rescale a picture to new dimension width x height. |
||
444 | // If either 'width' or 'height' (but not both) is 0 the corresponding |
||
445 | // dimension will be calculated preserving the aspect ratio. |
||
446 | // No gamma correction is applied. |
||
447 | // Returns false in case of error (invalid parameter or insufficient memory). |
||
448 | WEBP_EXTERN(int) WebPPictureRescale(WebPPicture* pic, int width, int height); |
||
449 | |||
450 | // Colorspace conversion function to import RGB samples. |
||
451 | // Previous buffer will be free'd, if any. |
||
452 | // *rgb buffer should have a size of at least height * rgb_stride. |
||
453 | // Returns false in case of memory error. |
||
454 | WEBP_EXTERN(int) WebPPictureImportRGB( |
||
455 | WebPPicture* picture, const uint8_t* rgb, int rgb_stride); |
||
456 | // Same, but for RGBA buffer. |
||
457 | WEBP_EXTERN(int) WebPPictureImportRGBA( |
||
458 | WebPPicture* picture, const uint8_t* rgba, int rgba_stride); |
||
459 | // Same, but for RGBA buffer. Imports the RGB direct from the 32-bit format |
||
460 | // input buffer ignoring the alpha channel. Avoids needing to copy the data |
||
461 | // to a temporary 24-bit RGB buffer to import the RGB only. |
||
462 | WEBP_EXTERN(int) WebPPictureImportRGBX( |
||
463 | WebPPicture* picture, const uint8_t* rgbx, int rgbx_stride); |
||
464 | |||
465 | // Variants of the above, but taking BGR(A|X) input. |
||
466 | WEBP_EXTERN(int) WebPPictureImportBGR( |
||
467 | WebPPicture* picture, const uint8_t* bgr, int bgr_stride); |
||
468 | WEBP_EXTERN(int) WebPPictureImportBGRA( |
||
469 | WebPPicture* picture, const uint8_t* bgra, int bgra_stride); |
||
470 | WEBP_EXTERN(int) WebPPictureImportBGRX( |
||
471 | WebPPicture* picture, const uint8_t* bgrx, int bgrx_stride); |
||
472 | |||
473 | // Converts picture->argb data to the YUV420A format. The 'colorspace' |
||
474 | // parameter is deprecated and should be equal to WEBP_YUV420. |
||
475 | // Upon return, picture->use_argb is set to false. The presence of real |
||
476 | // non-opaque transparent values is detected, and 'colorspace' will be |
||
477 | // adjusted accordingly. Note that this method is lossy. |
||
478 | // Returns false in case of error. |
||
479 | WEBP_EXTERN(int) WebPPictureARGBToYUVA(WebPPicture* picture, |
||
480 | WebPEncCSP /*colorspace = WEBP_YUV420*/); |
||
481 | |||
482 | // Same as WebPPictureARGBToYUVA(), but the conversion is done using |
||
483 | // pseudo-random dithering with a strength 'dithering' between |
||
484 | // 0.0 (no dithering) and 1.0 (maximum dithering). This is useful |
||
485 | // for photographic picture. |
||
486 | WEBP_EXTERN(int) WebPPictureARGBToYUVADithered( |
||
487 | WebPPicture* picture, WebPEncCSP colorspace, float dithering); |
||
488 | |||
489 | // Performs 'sharp' RGBA->YUVA420 downsampling and colorspace conversion. |
||
490 | // Downsampling is handled with extra care in case of color clipping. This |
||
491 | // method is roughly 2x slower than WebPPictureARGBToYUVA() but produces better |
||
492 | // and sharper YUV representation. |
||
493 | // Returns false in case of error. |
||
494 | WEBP_EXTERN(int) WebPPictureSharpARGBToYUVA(WebPPicture* picture); |
||
495 | // kept for backward compatibility: |
||
496 | WEBP_EXTERN(int) WebPPictureSmartARGBToYUVA(WebPPicture* picture); |
||
497 | |||
498 | // Converts picture->yuv to picture->argb and sets picture->use_argb to true. |
||
499 | // The input format must be YUV_420 or YUV_420A. The conversion from YUV420 to |
||
500 | // ARGB incurs a small loss too. |
||
501 | // Note that the use of this colorspace is discouraged if one has access to the |
||
502 | // raw ARGB samples, since using YUV420 is comparatively lossy. |
||
503 | // Returns false in case of error. |
||
504 | WEBP_EXTERN(int) WebPPictureYUVAToARGB(WebPPicture* picture); |
||
505 | |||
506 | // Helper function: given a width x height plane of RGBA or YUV(A) samples |
||
507 | // clean-up the YUV or RGB samples under fully transparent area, to help |
||
508 | // compressibility (no guarantee, though). |
||
509 | WEBP_EXTERN(void) WebPCleanupTransparentArea(WebPPicture* picture); |
||
510 | |||
511 | // Scan the picture 'picture' for the presence of non fully opaque alpha values. |
||
512 | // Returns true in such case. Otherwise returns false (indicating that the |
||
513 | // alpha plane can be ignored altogether e.g.). |
||
514 | WEBP_EXTERN(int) WebPPictureHasTransparency(const WebPPicture* picture); |
||
515 | |||
516 | // Remove the transparency information (if present) by blending the color with |
||
517 | // the background color 'background_rgb' (specified as 24bit RGB triplet). |
||
518 | // After this call, all alpha values are reset to 0xff. |
||
519 | WEBP_EXTERN(void) WebPBlendAlpha(WebPPicture* pic, uint32_t background_rgb); |
||
520 | |||
521 | //------------------------------------------------------------------------------ |
||
522 | // Main call |
||
523 | |||
524 | // Main encoding call, after config and picture have been initialized. |
||
525 | // 'picture' must be less than 16384x16384 in dimension (cf WEBP_MAX_DIMENSION), |
||
526 | // and the 'config' object must be a valid one. |
||
527 | // Returns false in case of error, true otherwise. |
||
528 | // In case of error, picture->error_code is updated accordingly. |
||
529 | // 'picture' can hold the source samples in both YUV(A) or ARGB input, depending |
||
530 | // on the value of 'picture->use_argb'. It is highly recommended to use |
||
531 | // the former for lossy encoding, and the latter for lossless encoding |
||
532 | // (when config.lossless is true). Automatic conversion from one format to |
||
533 | // another is provided but they both incur some loss. |
||
534 | WEBP_EXTERN(int) WebPEncode(const WebPConfig* config, WebPPicture* picture); |
||
535 | |||
536 | //------------------------------------------------------------------------------ |
||
537 | |||
538 | #ifdef __cplusplus |
||
539 | } // extern "C" |
||
540 | #endif |
||
541 | |||
542 | #endif /* WEBP_WEBP_ENCODE_H_ */ |