xref: /PHP-5.6/ext/gd/libgd/webpimg.h (revision 4dc99457)
1 /*===========================================================================*
2  - Copyright 2010 Google Inc.
3  -
4  - This code is licensed under the same terms as WebM:
5  - Software License Agreement:  http://www.webmproject.org/license/software/
6  - Additional IP Rights Grant:  http://www.webmproject.org/license/additional/
7  *===========================================================================*/
8 
9 /*
10  * Encoding/Decoding of WebP still image compression format.
11  *
12  * 1. WebPDecode: Takes an array of bytes (string) corresponding to the WebP
13  *                encoded image and generates output in the YUV format with
14  *                the color components U, V subsampled to 1/2 resolution along
15  *                each dimension.
16  *
17  * 2. YUV420toRGBA: Converts from YUV (with color subsampling) such as produced
18  *                  by the WebPDecode routine into 32 bits per pixel RGBA data
19  *                  array. This data array can be directly used by the Leptonica
20  *                  Pix in-memory image format.
21  *
22  * 3. WebPEncode: Takes a Y, U, V data buffers (with color components U and V
23  *                subsampled to 1/2 resolution) and generates the WebP string
24  *
25  * 4. RGBAToYUV420: Generates Y, U, V data (with color subsampling) from 32 bits
26  *                  per pixel RGBA data buffer. The resulting YUV data can be
27  *                  directly fed into the WebPEncode routine.
28  *
29  * 5. AdjustColorspace:
30  *
31  * 6. AdjustColorspaceBack:
32  */
33 
34 #ifndef THIRD_PARTY_VP8_VP8IMG_H_
35 #define THIRD_PARTY_VP8_VP8IMG_H_
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif  /* __cplusplus */
40 
41 typedef unsigned char uint8;
42 typedef unsigned int uint32;
43 typedef enum WebPResultType {
44   webp_success = 0,
45   webp_failure = -1
46 } WebPResult;
47 
48 /* Takes an array of bytes (string) corresponding to the WebP
49  * encoded image and generates output in the YUV format with
50  * the color components U, V subsampled to 1/2 resolution along
51  * each dimension.
52  * Input:
53  *      1. data: the WebP data stream (array of bytes)
54  *      2. data_size: count of bytes in the WebP data stream
55  *
56  * Output:
57  *      3. p_Y/p_U/p_V : pointer to the Y/U/V data buffer (this routine will
58  *                       allocate memory for the buffer, fill the buffer with
59  *                       appropriate data and transfer owner ship of the buffer
60  *                       to caller. Caller is responsible for freeing the memory).
61  *                       Note that the memory for Y, U, V buffers is alloacted
62  *                       in one chunk, hence one should call free(*p_Y) only.
63  *                       Do not try to free the U and V buffers.
64  *
65  *      6. p_width: this routine returns the width of the decoded image here
66  *      7. p_height: this routine returns the width of the decoded image here
67  * Return: success/failure
68  */
69 WebPResult WebPDecode(const uint8* data,
70                       int data_size,
71                       uint8** p_Y,
72                       uint8** p_U,
73                       uint8** p_V,
74                       int* p_width,
75                       int* p_height);
76 
77 /* WebPEncode: Takes a Y, U, V data buffers (with color components U and V
78  *             subsampled to 1/2 resolution) and generates the WebP string.
79  * Input:
80  *      1, 2, 3. Y, U, V: The input YUV data buffers
81  *      4, 5. y_width, y_height: The width and height of the image whose data
82  *                               is in Y, U, V. This matches the Y plane. The U
83  *                               and V planes typically have 1/2 width and
84  *                               height.
85  *      6. y_stride: The width (in bytes) of one row of Y data. This may not
86  *                   match width if there is end of row padding (e.g., for 32
87  *                   bit row alignment).
88  *      7. QP: the quantization parameter. This parameter controls the
89  *             compression vs quality tradeoff. Use smaller numbers for better
90  *             quality (compression will be lesser) and vice versa. 20 is a
91  *             good optimal value.
92  * Output:
93  *      8. p_out: the output array of bytes corresponding to the encoded WebP
94  *                image. This routine allocates memory for the buffer, fills it
95  *                with appropriate values and transfers ownership to caller.
96  *                Caller responsible for freeing of memory.
97  * Return: success/failure
98  */
99 WebPResult WebPEncode(const uint8* Y,
100                       const uint8* U,
101                       const uint8* V,
102                       int y_width,
103                       int y_height,
104                       int y_stride,
105                       int uv_width,
106                       int uv_height,
107                       int uv_stride,
108                       int QP,
109                       unsigned char** p_out,
110                       int* p_out_size_bytes,
111                       double* psnr);
112 
113 /* Converts from YUV (with color subsampling) such as produced by the WebPDecode
114  * routine into 32 bits per pixel RGBA data array. This data array can be
115  * directly used by the Leptonica Pix in-memory image format.
116  * Input:
117  *      1, 2, 3. Y, U, V: the input data buffers
118  *      4. pixwpl: the desired words per line corresponding to the supplied
119  *                 output pixdata.
120  *      5. width, height: the dimensions of the image whose data resides in Y,
121  *                        U, V.
122  * Output:
123  *     6. pixdata: the output data buffer. Caller should allocate
124  *                 height * pixwpl bytes of memory before calling this routine.
125  */
126 void YUV420toRGBA(uint8* Y,
127                   uint8* U,
128                   uint8* V,
129                   int words_per_line,
130                   int width,
131                   int height,
132                   uint32* pixdata);
133 
134 /* Generates Y, U, V data (with color subsampling) from 32 bits
135  * per pixel RGBA data buffer. The resulting YUV data can be directly fed into
136  * the WebPEncode routine.
137  * Input:
138  *    1. pix data input rgba data buffer
139  *    2. words per line corresponding to pixdata
140  *    3, 4. image width and height respectively
141  * Output:
142  *    5, 6, 7. Output YUV data buffers
143  */
144 void RGBAToYUV420(uint32* pixdata,
145                   int words_per_line,
146                   int width,
147                   int height,
148                   uint8* Y,
149                   uint8* U,
150                   uint8* V);
151 
152 /* This function adjust from YUV420J (jpeg decoding) to YUV420 (webp input)
153  * Hints: http://en.wikipedia.org/wiki/YCbCr
154  */
155 void AdjustColorspace(uint8* Y, uint8* U, uint8* V, int width, int height);
156 
157 /* Inverse function: convert from YUV420 to YUV420J */
158 void AdjustColorspaceBack(uint8* Y, uint8* U, uint8* V, int width, int height);
159 
160 /* Checks WebP image header and outputs height and width information of
161  * the image
162  *
163  * Input:
164  *      1. data: the WebP data stream (array of bytes)
165  *      2. data_size: count of bytes in the WebP data stream
166  *
167  * Outut:
168  *      width/height: width and height of the image
169  *
170  * Return: success/failure
171  */
172 WebPResult WebPGetInfo(const uint8* data,
173                        int data_size,
174                        int *width,
175                        int *height);
176 
177 #ifdef __cplusplus
178 }
179 #endif  /* __cplusplus */
180 
181 #endif  /* THIRD_PARTY_VP8_VP8IMG_H_ */
182