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