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