/work/include/webp/decode.h
Line | Count | Source (jump to first uncovered line) |
1 | | // Copyright 2010 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 | | // Main decoding functions for WebP images. |
11 | | // |
12 | | // Author: Skal (pascal.massimino@gmail.com) |
13 | | |
14 | | #ifndef WEBP_WEBP_DECODE_H_ |
15 | | #define WEBP_WEBP_DECODE_H_ |
16 | | |
17 | | #include <stddef.h> |
18 | | |
19 | | #include "./types.h" |
20 | | |
21 | | #ifdef __cplusplus |
22 | | extern "C" { |
23 | | #endif |
24 | | |
25 | 20.5k | #define WEBP_DECODER_ABI_VERSION 0x0210 // MAJOR(8b) + MINOR(8b) |
26 | | |
27 | | // Note: forward declaring enumerations is not allowed in (strict) C and C++, |
28 | | // the types are left here for reference. |
29 | | // typedef enum VP8StatusCode VP8StatusCode; |
30 | | // typedef enum WEBP_CSP_MODE WEBP_CSP_MODE; |
31 | | typedef struct WebPRGBABuffer WebPRGBABuffer; |
32 | | typedef struct WebPYUVABuffer WebPYUVABuffer; |
33 | | typedef struct WebPDecBuffer WebPDecBuffer; |
34 | | typedef struct WebPIDecoder WebPIDecoder; |
35 | | typedef struct WebPBitstreamFeatures WebPBitstreamFeatures; |
36 | | typedef struct WebPDecoderOptions WebPDecoderOptions; |
37 | | typedef struct WebPDecoderConfig WebPDecoderConfig; |
38 | | |
39 | | // Return the decoder's version number, packed in hexadecimal using 8bits for |
40 | | // each of major/minor/revision. E.g: v2.5.7 is 0x020507. |
41 | | WEBP_EXTERN int WebPGetDecoderVersion(void); |
42 | | |
43 | | // Retrieve basic header information: width, height. |
44 | | // This function will also validate the header, returning true on success, |
45 | | // false otherwise. '*width' and '*height' are only valid on successful return. |
46 | | // Pointers 'width' and 'height' can be passed NULL if deemed irrelevant. |
47 | | // Note: The following chunk sequences (before the raw VP8/VP8L data) are |
48 | | // considered valid by this function: |
49 | | // RIFF + VP8(L) |
50 | | // RIFF + VP8X + (optional chunks) + VP8(L) |
51 | | // ALPH + VP8 <-- Not a valid WebP format: only allowed for internal purpose. |
52 | | // VP8(L) <-- Not a valid WebP format: only allowed for internal purpose. |
53 | | WEBP_NODISCARD WEBP_EXTERN int WebPGetInfo( |
54 | | const uint8_t* data, size_t data_size, int* width, int* height); |
55 | | |
56 | | // Decodes WebP images pointed to by 'data' and returns RGBA samples, along |
57 | | // with the dimensions in *width and *height. The ordering of samples in |
58 | | // memory is R, G, B, A, R, G, B, A... in scan order (endian-independent). |
59 | | // The returned pointer should be deleted calling WebPFree(). |
60 | | // Returns NULL in case of error. |
61 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeRGBA( |
62 | | const uint8_t* data, size_t data_size, int* width, int* height); |
63 | | |
64 | | // Same as WebPDecodeRGBA, but returning A, R, G, B, A, R, G, B... ordered data. |
65 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeARGB( |
66 | | const uint8_t* data, size_t data_size, int* width, int* height); |
67 | | |
68 | | // Same as WebPDecodeRGBA, but returning B, G, R, A, B, G, R, A... ordered data. |
69 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeBGRA( |
70 | | const uint8_t* data, size_t data_size, int* width, int* height); |
71 | | |
72 | | // Same as WebPDecodeRGBA, but returning R, G, B, R, G, B... ordered data. |
73 | | // If the bitstream contains transparency, it is ignored. |
74 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeRGB( |
75 | | const uint8_t* data, size_t data_size, int* width, int* height); |
76 | | |
77 | | // Same as WebPDecodeRGB, but returning B, G, R, B, G, R... ordered data. |
78 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeBGR( |
79 | | const uint8_t* data, size_t data_size, int* width, int* height); |
80 | | |
81 | | // Decode WebP images pointed to by 'data' to Y'UV format(*). The pointer |
82 | | // returned is the Y samples buffer. Upon return, *u and *v will point to |
83 | | // the U and V chroma data. These U and V buffers need NOT be passed to |
84 | | // WebPFree(), unlike the returned Y luma one. The dimension of the U and V |
85 | | // planes are both (*width + 1) / 2 and (*height + 1) / 2. |
86 | | // Upon return, the Y buffer has a stride returned as '*stride', while U and V |
87 | | // have a common stride returned as '*uv_stride'. |
88 | | // 'width' and 'height' may be NULL, the other pointers must not be. |
89 | | // Returns NULL in case of error. |
90 | | // (*) Also named Y'CbCr. See: https://en.wikipedia.org/wiki/YCbCr |
91 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeYUV( |
92 | | const uint8_t* data, size_t data_size, int* width, int* height, |
93 | | uint8_t** u, uint8_t** v, int* stride, int* uv_stride); |
94 | | |
95 | | // These five functions are variants of the above ones, that decode the image |
96 | | // directly into a pre-allocated buffer 'output_buffer'. The maximum storage |
97 | | // available in this buffer is indicated by 'output_buffer_size'. If this |
98 | | // storage is not sufficient (or an error occurred), NULL is returned. |
99 | | // Otherwise, output_buffer is returned, for convenience. |
100 | | // The parameter 'output_stride' specifies the distance (in bytes) |
101 | | // between scanlines. Hence, output_buffer_size is expected to be at least |
102 | | // output_stride x picture-height. |
103 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeRGBAInto( |
104 | | const uint8_t* data, size_t data_size, |
105 | | uint8_t* output_buffer, size_t output_buffer_size, int output_stride); |
106 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeARGBInto( |
107 | | const uint8_t* data, size_t data_size, |
108 | | uint8_t* output_buffer, size_t output_buffer_size, int output_stride); |
109 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeBGRAInto( |
110 | | const uint8_t* data, size_t data_size, |
111 | | uint8_t* output_buffer, size_t output_buffer_size, int output_stride); |
112 | | |
113 | | // RGB and BGR variants. Here too the transparency information, if present, |
114 | | // will be dropped and ignored. |
115 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeRGBInto( |
116 | | const uint8_t* data, size_t data_size, |
117 | | uint8_t* output_buffer, size_t output_buffer_size, int output_stride); |
118 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeBGRInto( |
119 | | const uint8_t* data, size_t data_size, |
120 | | uint8_t* output_buffer, size_t output_buffer_size, int output_stride); |
121 | | |
122 | | // WebPDecodeYUVInto() is a variant of WebPDecodeYUV() that operates directly |
123 | | // into pre-allocated luma/chroma plane buffers. This function requires the |
124 | | // strides to be passed: one for the luma plane and one for each of the |
125 | | // chroma ones. The size of each plane buffer is passed as 'luma_size', |
126 | | // 'u_size' and 'v_size' respectively. |
127 | | // Pointer to the luma plane ('*luma') is returned or NULL if an error occurred |
128 | | // during decoding (or because some buffers were found to be too small). |
129 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPDecodeYUVInto( |
130 | | const uint8_t* data, size_t data_size, |
131 | | uint8_t* luma, size_t luma_size, int luma_stride, |
132 | | uint8_t* u, size_t u_size, int u_stride, |
133 | | uint8_t* v, size_t v_size, int v_stride); |
134 | | |
135 | | //------------------------------------------------------------------------------ |
136 | | // Output colorspaces and buffer |
137 | | |
138 | | // Colorspaces |
139 | | // Note: the naming describes the byte-ordering of packed samples in memory. |
140 | | // For instance, MODE_BGRA relates to samples ordered as B,G,R,A,B,G,R,A,... |
141 | | // Non-capital names (e.g.:MODE_Argb) relates to pre-multiplied RGB channels. |
142 | | // RGBA-4444 and RGB-565 colorspaces are represented by following byte-order: |
143 | | // RGBA-4444: [r3 r2 r1 r0 g3 g2 g1 g0], [b3 b2 b1 b0 a3 a2 a1 a0], ... |
144 | | // RGB-565: [r4 r3 r2 r1 r0 g5 g4 g3], [g2 g1 g0 b4 b3 b2 b1 b0], ... |
145 | | // In the case WEBP_SWAP_16BITS_CSP is defined, the bytes are swapped for |
146 | | // these two modes: |
147 | | // RGBA-4444: [b3 b2 b1 b0 a3 a2 a1 a0], [r3 r2 r1 r0 g3 g2 g1 g0], ... |
148 | | // RGB-565: [g2 g1 g0 b4 b3 b2 b1 b0], [r4 r3 r2 r1 r0 g5 g4 g3], ... |
149 | | |
150 | | typedef enum WEBP_CSP_MODE { |
151 | | MODE_RGB = 0, MODE_RGBA = 1, |
152 | | MODE_BGR = 2, MODE_BGRA = 3, |
153 | | MODE_ARGB = 4, MODE_RGBA_4444 = 5, |
154 | | MODE_RGB_565 = 6, |
155 | | // RGB-premultiplied transparent modes (alpha value is preserved) |
156 | | MODE_rgbA = 7, |
157 | | MODE_bgrA = 8, |
158 | | MODE_Argb = 9, |
159 | | MODE_rgbA_4444 = 10, |
160 | | // YUV modes must come after RGB ones. |
161 | | MODE_YUV = 11, MODE_YUVA = 12, // yuv 4:2:0 |
162 | | MODE_LAST = 13 |
163 | | } WEBP_CSP_MODE; |
164 | | |
165 | | // Some useful macros: |
166 | 0 | static WEBP_INLINE int WebPIsPremultipliedMode(WEBP_CSP_MODE mode) { |
167 | 0 | return (mode == MODE_rgbA || mode == MODE_bgrA || mode == MODE_Argb || |
168 | 0 | mode == MODE_rgbA_4444); |
169 | 0 | } |
170 | | |
171 | 0 | static WEBP_INLINE int WebPIsAlphaMode(WEBP_CSP_MODE mode) { |
172 | 0 | return (mode == MODE_RGBA || mode == MODE_BGRA || mode == MODE_ARGB || |
173 | 0 | mode == MODE_RGBA_4444 || mode == MODE_YUVA || |
174 | 0 | WebPIsPremultipliedMode(mode)); |
175 | 0 | } |
176 | | |
177 | 0 | static WEBP_INLINE int WebPIsRGBMode(WEBP_CSP_MODE mode) { |
178 | 0 | return (mode < MODE_YUV); |
179 | 0 | } |
180 | | |
181 | | //------------------------------------------------------------------------------ |
182 | | // WebPDecBuffer: Generic structure for describing the output sample buffer. |
183 | | |
184 | | struct WebPRGBABuffer { // view as RGBA |
185 | | uint8_t* rgba; // pointer to RGBA samples |
186 | | int stride; // stride in bytes from one scanline to the next. |
187 | | size_t size; // total size of the *rgba buffer. |
188 | | }; |
189 | | |
190 | | struct WebPYUVABuffer { // view as YUVA |
191 | | uint8_t* y, *u, *v, *a; // pointer to luma, chroma U/V, alpha samples |
192 | | int y_stride; // luma stride |
193 | | int u_stride, v_stride; // chroma strides |
194 | | int a_stride; // alpha stride |
195 | | size_t y_size; // luma plane size |
196 | | size_t u_size, v_size; // chroma planes size |
197 | | size_t a_size; // alpha-plane size |
198 | | }; |
199 | | |
200 | | // Output buffer |
201 | | struct WebPDecBuffer { |
202 | | WEBP_CSP_MODE colorspace; // Colorspace. |
203 | | int width, height; // Dimensions. |
204 | | int is_external_memory; // If non-zero, 'internal_memory' pointer is not |
205 | | // used. If value is '2' or more, the external |
206 | | // memory is considered 'slow' and multiple |
207 | | // read/write will be avoided. |
208 | | union { |
209 | | WebPRGBABuffer RGBA; |
210 | | WebPYUVABuffer YUVA; |
211 | | } u; // Nameless union of buffer parameters. |
212 | | uint32_t pad[4]; // padding for later use |
213 | | |
214 | | uint8_t* private_memory; // Internally allocated memory (only when |
215 | | // is_external_memory is 0). Should not be used |
216 | | // externally, but accessed via the buffer union. |
217 | | }; |
218 | | |
219 | | // Internal, version-checked, entry point |
220 | | WEBP_NODISCARD WEBP_EXTERN int WebPInitDecBufferInternal(WebPDecBuffer*, int); |
221 | | |
222 | | // Initialize the structure as empty. Must be called before any other use. |
223 | | // Returns false in case of version mismatch |
224 | 0 | WEBP_NODISCARD static WEBP_INLINE int WebPInitDecBuffer(WebPDecBuffer* buffer) { |
225 | 0 | return WebPInitDecBufferInternal(buffer, WEBP_DECODER_ABI_VERSION); |
226 | 0 | } |
227 | | |
228 | | // Free any memory associated with the buffer. Must always be called last. |
229 | | // Note: doesn't free the 'buffer' structure itself. |
230 | | WEBP_EXTERN void WebPFreeDecBuffer(WebPDecBuffer* buffer); |
231 | | |
232 | | //------------------------------------------------------------------------------ |
233 | | // Enumeration of the status codes |
234 | | |
235 | | typedef enum WEBP_NODISCARD VP8StatusCode { |
236 | | VP8_STATUS_OK = 0, |
237 | | VP8_STATUS_OUT_OF_MEMORY, |
238 | | VP8_STATUS_INVALID_PARAM, |
239 | | VP8_STATUS_BITSTREAM_ERROR, |
240 | | VP8_STATUS_UNSUPPORTED_FEATURE, |
241 | | VP8_STATUS_SUSPENDED, |
242 | | VP8_STATUS_USER_ABORT, |
243 | | VP8_STATUS_NOT_ENOUGH_DATA |
244 | | } VP8StatusCode; |
245 | | |
246 | | //------------------------------------------------------------------------------ |
247 | | // Incremental decoding |
248 | | // |
249 | | // This API allows streamlined decoding of partial data. |
250 | | // Picture can be incrementally decoded as data become available thanks to the |
251 | | // WebPIDecoder object. This object can be left in a SUSPENDED state if the |
252 | | // picture is only partially decoded, pending additional input. |
253 | | // Code example: |
254 | | /* |
255 | | WebPInitDecBuffer(&output_buffer); |
256 | | output_buffer.colorspace = mode; |
257 | | ... |
258 | | WebPIDecoder* idec = WebPINewDecoder(&output_buffer); |
259 | | while (additional_data_is_available) { |
260 | | // ... (get additional data in some new_data[] buffer) |
261 | | status = WebPIAppend(idec, new_data, new_data_size); |
262 | | if (status != VP8_STATUS_OK && status != VP8_STATUS_SUSPENDED) { |
263 | | break; // an error occurred. |
264 | | } |
265 | | |
266 | | // The above call decodes the current available buffer. |
267 | | // Part of the image can now be refreshed by calling |
268 | | // WebPIDecGetRGB()/WebPIDecGetYUVA() etc. |
269 | | } |
270 | | WebPIDelete(idec); |
271 | | */ |
272 | | |
273 | | // Creates a new incremental decoder with the supplied buffer parameter. |
274 | | // This output_buffer can be passed NULL, in which case a default output buffer |
275 | | // is used (with MODE_RGB). Otherwise, an internal reference to 'output_buffer' |
276 | | // is kept, which means that the lifespan of 'output_buffer' must be larger than |
277 | | // that of the returned WebPIDecoder object. |
278 | | // The supplied 'output_buffer' content MUST NOT be changed between calls to |
279 | | // WebPIAppend() or WebPIUpdate() unless 'output_buffer.is_external_memory' is |
280 | | // not set to 0. In such a case, it is allowed to modify the pointers, size and |
281 | | // stride of output_buffer.u.RGBA or output_buffer.u.YUVA, provided they remain |
282 | | // within valid bounds. |
283 | | // All other fields of WebPDecBuffer MUST remain constant between calls. |
284 | | // Returns NULL if the allocation failed. |
285 | | WEBP_NODISCARD WEBP_EXTERN WebPIDecoder* WebPINewDecoder( |
286 | | WebPDecBuffer* output_buffer); |
287 | | |
288 | | // This function allocates and initializes an incremental-decoder object, which |
289 | | // will output the RGB/A samples specified by 'csp' into a preallocated |
290 | | // buffer 'output_buffer'. The size of this buffer is at least |
291 | | // 'output_buffer_size' and the stride (distance in bytes between two scanlines) |
292 | | // is specified by 'output_stride'. |
293 | | // Additionally, output_buffer can be passed NULL in which case the output |
294 | | // buffer will be allocated automatically when the decoding starts. The |
295 | | // colorspace 'csp' is taken into account for allocating this buffer. All other |
296 | | // parameters are ignored. |
297 | | // Returns NULL if the allocation failed, or if some parameters are invalid. |
298 | | WEBP_NODISCARD WEBP_EXTERN WebPIDecoder* WebPINewRGB( |
299 | | WEBP_CSP_MODE csp, |
300 | | uint8_t* output_buffer, size_t output_buffer_size, int output_stride); |
301 | | |
302 | | // This function allocates and initializes an incremental-decoder object, which |
303 | | // will output the raw luma/chroma samples into a preallocated planes if |
304 | | // supplied. The luma plane is specified by its pointer 'luma', its size |
305 | | // 'luma_size' and its stride 'luma_stride'. Similarly, the chroma-u plane |
306 | | // is specified by the 'u', 'u_size' and 'u_stride' parameters, and the chroma-v |
307 | | // plane by 'v' and 'v_size'. And same for the alpha-plane. The 'a' pointer |
308 | | // can be pass NULL in case one is not interested in the transparency plane. |
309 | | // Conversely, 'luma' can be passed NULL if no preallocated planes are supplied. |
310 | | // In this case, the output buffer will be automatically allocated (using |
311 | | // MODE_YUVA) when decoding starts. All parameters are then ignored. |
312 | | // Returns NULL if the allocation failed or if a parameter is invalid. |
313 | | WEBP_NODISCARD WEBP_EXTERN WebPIDecoder* WebPINewYUVA( |
314 | | uint8_t* luma, size_t luma_size, int luma_stride, |
315 | | uint8_t* u, size_t u_size, int u_stride, |
316 | | uint8_t* v, size_t v_size, int v_stride, |
317 | | uint8_t* a, size_t a_size, int a_stride); |
318 | | |
319 | | // Deprecated version of the above, without the alpha plane. |
320 | | // Kept for backward compatibility. |
321 | | WEBP_NODISCARD WEBP_EXTERN WebPIDecoder* WebPINewYUV( |
322 | | uint8_t* luma, size_t luma_size, int luma_stride, |
323 | | uint8_t* u, size_t u_size, int u_stride, |
324 | | uint8_t* v, size_t v_size, int v_stride); |
325 | | |
326 | | // Deletes the WebPIDecoder object and associated memory. Must always be called |
327 | | // if WebPINewDecoder, WebPINewRGB or WebPINewYUV succeeded. |
328 | | WEBP_EXTERN void WebPIDelete(WebPIDecoder* idec); |
329 | | |
330 | | // Copies and decodes the next available data. Returns VP8_STATUS_OK when |
331 | | // the image is successfully decoded. Returns VP8_STATUS_SUSPENDED when more |
332 | | // data is expected. Returns error in other cases. |
333 | | WEBP_EXTERN VP8StatusCode WebPIAppend( |
334 | | WebPIDecoder* idec, const uint8_t* data, size_t data_size); |
335 | | |
336 | | // A variant of the above function to be used when data buffer contains |
337 | | // partial data from the beginning. In this case data buffer is not copied |
338 | | // to the internal memory. |
339 | | // Note that the value of the 'data' pointer can change between calls to |
340 | | // WebPIUpdate, for instance when the data buffer is resized to fit larger data. |
341 | | WEBP_EXTERN VP8StatusCode WebPIUpdate( |
342 | | WebPIDecoder* idec, const uint8_t* data, size_t data_size); |
343 | | |
344 | | // Returns the RGB/A image decoded so far. Returns NULL if output params |
345 | | // are not initialized yet. The RGB/A output type corresponds to the colorspace |
346 | | // specified during call to WebPINewDecoder() or WebPINewRGB(). |
347 | | // *last_y is the index of last decoded row in raster scan order. Some pointers |
348 | | // (*last_y, *width etc.) can be NULL if corresponding information is not |
349 | | // needed. The values in these pointers are only valid on successful (non-NULL) |
350 | | // return. |
351 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPIDecGetRGB( |
352 | | const WebPIDecoder* idec, int* last_y, |
353 | | int* width, int* height, int* stride); |
354 | | |
355 | | // Same as above function to get a YUVA image. Returns pointer to the luma |
356 | | // plane or NULL in case of error. If there is no alpha information |
357 | | // the alpha pointer '*a' will be returned NULL. |
358 | | WEBP_NODISCARD WEBP_EXTERN uint8_t* WebPIDecGetYUVA( |
359 | | const WebPIDecoder* idec, int* last_y, |
360 | | uint8_t** u, uint8_t** v, uint8_t** a, |
361 | | int* width, int* height, int* stride, int* uv_stride, int* a_stride); |
362 | | |
363 | | // Deprecated alpha-less version of WebPIDecGetYUVA(): it will ignore the |
364 | | // alpha information (if present). Kept for backward compatibility. |
365 | | WEBP_NODISCARD static WEBP_INLINE uint8_t* WebPIDecGetYUV( |
366 | | const WebPIDecoder* idec, int* last_y, uint8_t** u, uint8_t** v, |
367 | 0 | int* width, int* height, int* stride, int* uv_stride) { |
368 | 0 | return WebPIDecGetYUVA(idec, last_y, u, v, NULL, width, height, |
369 | 0 | stride, uv_stride, NULL); |
370 | 0 | } |
371 | | |
372 | | // Generic call to retrieve information about the displayable area. |
373 | | // If non NULL, the left/right/width/height pointers are filled with the visible |
374 | | // rectangular area so far. |
375 | | // Returns NULL in case the incremental decoder object is in an invalid state. |
376 | | // Otherwise returns the pointer to the internal representation. This structure |
377 | | // is read-only, tied to WebPIDecoder's lifespan and should not be modified. |
378 | | WEBP_NODISCARD WEBP_EXTERN const WebPDecBuffer* WebPIDecodedArea( |
379 | | const WebPIDecoder* idec, int* left, int* top, int* width, int* height); |
380 | | |
381 | | //------------------------------------------------------------------------------ |
382 | | // Advanced decoding parametrization |
383 | | // |
384 | | // Code sample for using the advanced decoding API |
385 | | /* |
386 | | // A) Init a configuration object |
387 | | WebPDecoderConfig config; |
388 | | CHECK(WebPInitDecoderConfig(&config)); |
389 | | |
390 | | // B) optional: retrieve the bitstream's features. |
391 | | CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK); |
392 | | |
393 | | // C) Adjust 'config', if needed |
394 | | config.options.no_fancy_upsampling = 1; |
395 | | config.output.colorspace = MODE_BGRA; |
396 | | // etc. |
397 | | |
398 | | // Note that you can also make config.output point to an externally |
399 | | // supplied memory buffer, provided it's big enough to store the decoded |
400 | | // picture. Otherwise, config.output will just be used to allocate memory |
401 | | // and store the decoded picture. |
402 | | |
403 | | // D) Decode! |
404 | | CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK); |
405 | | |
406 | | // E) Decoded image is now in config.output (and config.output.u.RGBA) |
407 | | |
408 | | // F) Reclaim memory allocated in config's object. It's safe to call |
409 | | // this function even if the memory is external and wasn't allocated |
410 | | // by WebPDecode(). |
411 | | WebPFreeDecBuffer(&config.output); |
412 | | */ |
413 | | |
414 | | // Features gathered from the bitstream |
415 | | struct WebPBitstreamFeatures { |
416 | | int width; // Width in pixels, as read from the bitstream. |
417 | | int height; // Height in pixels, as read from the bitstream. |
418 | | int has_alpha; // True if the bitstream contains an alpha channel. |
419 | | int has_animation; // True if the bitstream is an animation. |
420 | | int format; // 0 = undefined (/mixed), 1 = lossy, 2 = lossless |
421 | | |
422 | | uint32_t pad[5]; // padding for later use |
423 | | }; |
424 | | |
425 | | // Internal, version-checked, entry point |
426 | | WEBP_EXTERN VP8StatusCode WebPGetFeaturesInternal( |
427 | | const uint8_t*, size_t, WebPBitstreamFeatures*, int); |
428 | | |
429 | | // Retrieve features from the bitstream. The *features structure is filled |
430 | | // with information gathered from the bitstream. |
431 | | // Returns VP8_STATUS_OK when the features are successfully retrieved. Returns |
432 | | // VP8_STATUS_NOT_ENOUGH_DATA when more data is needed to retrieve the |
433 | | // features from headers. Returns error in other cases. |
434 | | // Note: The following chunk sequences (before the raw VP8/VP8L data) are |
435 | | // considered valid by this function: |
436 | | // RIFF + VP8(L) |
437 | | // RIFF + VP8X + (optional chunks) + VP8(L) |
438 | | // ALPH + VP8 <-- Not a valid WebP format: only allowed for internal purpose. |
439 | | // VP8(L) <-- Not a valid WebP format: only allowed for internal purpose. |
440 | | static WEBP_INLINE VP8StatusCode WebPGetFeatures( |
441 | | const uint8_t* data, size_t data_size, |
442 | 13.9k | WebPBitstreamFeatures* features) { |
443 | 13.9k | return WebPGetFeaturesInternal(data, data_size, features, |
444 | 13.9k | WEBP_DECODER_ABI_VERSION); |
445 | 13.9k | } |
446 | | |
447 | | // Decoding options |
448 | | struct WebPDecoderOptions { |
449 | | int bypass_filtering; // if true, skip the in-loop filtering |
450 | | int no_fancy_upsampling; // if true, use faster pointwise upsampler |
451 | | int use_cropping; // if true, cropping is applied _first_ |
452 | | int crop_left, crop_top; // top-left position for cropping. |
453 | | // Will be snapped to even values. |
454 | | int crop_width, crop_height; // dimension of the cropping area |
455 | | int use_scaling; // if true, scaling is applied _afterward_ |
456 | | int scaled_width, scaled_height; // final resolution. if one is 0, it is |
457 | | // guessed from the other one to keep the |
458 | | // original ratio. |
459 | | int use_threads; // if true, use multi-threaded decoding |
460 | | int dithering_strength; // dithering strength (0=Off, 100=full) |
461 | | int flip; // if true, flip output vertically |
462 | | int alpha_dithering_strength; // alpha dithering strength in [0..100] |
463 | | |
464 | | uint32_t pad[5]; // padding for later use |
465 | | }; |
466 | | |
467 | | // Main object storing the configuration for advanced decoding. |
468 | | struct WebPDecoderConfig { |
469 | | WebPBitstreamFeatures input; // Immutable bitstream features (optional) |
470 | | WebPDecBuffer output; // Output buffer (can point to external mem) |
471 | | WebPDecoderOptions options; // Decoding options |
472 | | }; |
473 | | |
474 | | // Internal, version-checked, entry point |
475 | | WEBP_NODISCARD WEBP_EXTERN int WebPInitDecoderConfigInternal(WebPDecoderConfig*, |
476 | | int); |
477 | | |
478 | | // Initialize the configuration as empty. This function must always be |
479 | | // called first, unless WebPGetFeatures() is to be called. |
480 | | // Returns false in case of mismatched version. |
481 | | WEBP_NODISCARD static WEBP_INLINE int WebPInitDecoderConfig( |
482 | 6.61k | WebPDecoderConfig* config) { |
483 | 6.61k | return WebPInitDecoderConfigInternal(config, WEBP_DECODER_ABI_VERSION); |
484 | 6.61k | } |
485 | | |
486 | | // Returns true if 'config' is non-NULL and all configuration parameters are |
487 | | // within their valid ranges. |
488 | | WEBP_NODISCARD WEBP_EXTERN int WebPValidateDecoderConfig( |
489 | | const WebPDecoderConfig* config); |
490 | | |
491 | | // Instantiate a new incremental decoder object with the requested |
492 | | // configuration. The bitstream can be passed using 'data' and 'data_size' |
493 | | // parameter, in which case the features will be parsed and stored into |
494 | | // config->input. Otherwise, 'data' can be NULL and no parsing will occur. |
495 | | // Note that 'config' can be NULL too, in which case a default configuration |
496 | | // is used. If 'config' is not NULL, it must outlive the WebPIDecoder object |
497 | | // as some references to its fields will be used. No internal copy of 'config' |
498 | | // is made. |
499 | | // The return WebPIDecoder object must always be deleted calling WebPIDelete(). |
500 | | // Returns NULL in case of error (and config->status will then reflect |
501 | | // the error condition, if available). |
502 | | WEBP_NODISCARD WEBP_EXTERN WebPIDecoder* WebPIDecode( |
503 | | const uint8_t* data, size_t data_size, WebPDecoderConfig* config); |
504 | | |
505 | | // Non-incremental version. This version decodes the full data at once, taking |
506 | | // 'config' into account. Returns decoding status (which should be VP8_STATUS_OK |
507 | | // if the decoding was successful). Note that 'config' cannot be NULL. |
508 | | WEBP_EXTERN VP8StatusCode WebPDecode(const uint8_t* data, size_t data_size, |
509 | | WebPDecoderConfig* config); |
510 | | |
511 | | #ifdef __cplusplus |
512 | | } // extern "C" |
513 | | #endif |
514 | | |
515 | | #endif // WEBP_WEBP_DECODE_H_ |