1// Copyright 2010 Google Inc.
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 "webp/types.h"
16
17#if defined(__cplusplus) || defined(c_plusplus)
18extern "C" {
19#endif
20
21// Retrieve basic header information: width, height.
22// This function will also validate the header and return 0 in
23// case of formatting error.
24// Pointers *width/*height can be passed NULL if deemed irrelevant.
25int WebPGetInfo(const uint8_t* data, uint32_t data_size,
26                int *width, int *height);
27
28// Decodes WEBP images pointed to by *data and returns RGB samples, along
29// with the dimensions in *width and *height.
30// The returned pointer should be deleted calling free().
31// Returns NULL in case of error.
32uint8_t* WebPDecodeRGB(const uint8_t* data, uint32_t data_size,
33                       int *width, int *height);
34
35// Same as WebPDecodeRGB, but returning RGBA data.
36uint8_t* WebPDecodeRGBA(const uint8_t* data, uint32_t data_size,
37                        int *width, int *height);
38
39// This variant decode to BGR instead of RGB.
40uint8_t* WebPDecodeBGR(const uint8_t* data, uint32_t data_size,
41                       int *width, int *height);
42// This variant decodes to BGRA instead of RGBA.
43uint8_t* WebPDecodeBGRA(const uint8_t* data, uint32_t data_size,
44                        int *width, int *height);
45
46// Decode WEBP images stored in *data in Y'UV format(*). The pointer returned is
47// the Y samples buffer. Upon return, *u and *v will point to the U and V
48// chroma data. These U and V buffers need NOT be free()'d, unlike the returned
49// Y luma one. The dimension of the U and V planes are both (*width + 1) / 2
50// and (*height + 1)/ 2.
51// Upon return, the Y buffer has a stride returned as '*stride', while U and V
52// have a common stride returned as '*uv_stride'.
53// Return NULL in case of error.
54// (*) Also named Y'CbCr. See: http://en.wikipedia.org/wiki/YCbCr
55uint8_t* WebPDecodeYUV(const uint8_t* data, uint32_t data_size,
56                       int *width, int *height, uint8_t** u, uint8_t** v,
57                       int *stride, int* uv_stride);
58
59// These three functions are variants of the above ones, that decode the image
60// directly into a pre-allocated buffer 'output_buffer'. The maximum storage
61// available in this buffer is indicated by 'output_buffer_size'. If this
62// storage is not sufficient (or an error occurred), NULL is returned.
63// Otherwise, output_buffer is returned, for convenience.
64// The parameter 'output_stride' specifies the distance (in bytes)
65// between scanlines. Hence, output_buffer_size is expected to be at least
66// output_stride x picture-height.
67uint8_t* WebPDecodeRGBInto(const uint8_t* data, uint32_t data_size,
68                           uint8_t* output_buffer, int output_buffer_size,
69                           int output_stride);
70uint8_t* WebPDecodeRGBAInto(const uint8_t* data, uint32_t data_size,
71                            uint8_t* output_buffer, int output_buffer_size,
72                            int output_stride);
73// BGR variants
74uint8_t* WebPDecodeBGRInto(const uint8_t* data, uint32_t data_size,
75                           uint8_t* output_buffer, int output_buffer_size,
76                           int output_stride);
77uint8_t* WebPDecodeBGRAInto(const uint8_t* data, uint32_t data_size,
78                            uint8_t* output_buffer, int output_buffer_size,
79                            int output_stride);
80
81// WebPDecodeYUVInto() is a variant of WebPDecodeYUV() that operates directly
82// into pre-allocated luma/chroma plane buffers. This function requires the
83// strides to be passed: one for the luma plane and one for each of the
84// chroma ones. The size of each plane buffer is passed as 'luma_size',
85// 'u_size' and 'v_size' respectively.
86// Pointer to the luma plane ('*luma') is returned or NULL if an error occurred
87// during decoding (or because some buffers were found to be too small).
88uint8_t* WebPDecodeYUVInto(const uint8_t* data, uint32_t data_size,
89                           uint8_t* luma, int luma_size, int luma_stride,
90                           uint8_t* u, int u_size, int u_stride,
91                           uint8_t* v, int v_size, int v_stride);
92
93//-----------------------------------------------------------------------------
94
95#if defined(__cplusplus) || defined(c_plusplus)
96}    // extern "C"
97#endif
98
99#endif  /* WEBP_WEBP_DECODE_H_ */
100