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