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 | // Low-level API for VP8 decoder |
11 | // |
12 | // Author: Skal (pascal.massimino@gmail.com) |
13 | |
14 | #ifndef WEBP_DEC_VP8_DEC_H_ |
15 | #define WEBP_DEC_VP8_DEC_H_ |
16 | |
17 | #include "src/webp/decode.h" |
18 | |
19 | #ifdef __cplusplus |
20 | extern "C" { |
21 | #endif |
22 | |
23 | //------------------------------------------------------------------------------ |
24 | // Lower-level API |
25 | // |
26 | // These functions provide fine-grained control of the decoding process. |
27 | // The call flow should resemble: |
28 | // |
29 | // VP8Io io; |
30 | // VP8InitIo(&io); |
31 | // io.data = data; |
32 | // io.data_size = size; |
33 | // /* customize io's functions (setup()/put()/teardown()) if needed. */ |
34 | // |
35 | // VP8Decoder* dec = VP8New(); |
36 | // int ok = VP8Decode(dec, &io); |
37 | // if (!ok) printf("Error: %s\n", VP8StatusMessage(dec)); |
38 | // VP8Delete(dec); |
39 | // return ok; |
40 | |
41 | // Input / Output |
42 | typedef struct VP8Io VP8Io; |
43 | typedef int (*VP8IoPutHook)(const VP8Io* io); |
44 | typedef int (*VP8IoSetupHook)(VP8Io* io); |
45 | typedef void (*VP8IoTeardownHook)(const VP8Io* io); |
46 | |
47 | struct VP8Io { |
48 | // set by VP8GetHeaders() |
49 | int width, height; // picture dimensions, in pixels (invariable). |
50 | // These are the original, uncropped dimensions. |
51 | // The actual area passed to put() is stored |
52 | // in mb_w / mb_h fields. |
53 | |
54 | // set before calling put() |
55 | int mb_y; // position of the current rows (in pixels) |
56 | int mb_w; // number of columns in the sample |
57 | int mb_h; // number of rows in the sample |
58 | const uint8_t* y, *u, *v; // rows to copy (in yuv420 format) |
59 | int y_stride; // row stride for luma |
60 | int uv_stride; // row stride for chroma |
61 | |
62 | void* opaque; // user data |
63 | |
64 | // called when fresh samples are available. Currently, samples are in |
65 | // YUV420 format, and can be up to width x 24 in size (depending on the |
66 | // in-loop filtering level, e.g.). Should return false in case of error |
67 | // or abort request. The actual size of the area to update is mb_w x mb_h |
68 | // in size, taking cropping into account. |
69 | VP8IoPutHook put; |
70 | |
71 | // called just before starting to decode the blocks. |
72 | // Must return false in case of setup error, true otherwise. If false is |
73 | // returned, teardown() will NOT be called. But if the setup succeeded |
74 | // and true is returned, then teardown() will always be called afterward. |
75 | VP8IoSetupHook setup; |
76 | |
77 | // Called just after block decoding is finished (or when an error occurred |
78 | // during put()). Is NOT called if setup() failed. |
79 | VP8IoTeardownHook teardown; |
80 | |
81 | // this is a recommendation for the user-side yuv->rgb converter. This flag |
82 | // is set when calling setup() hook and can be overwritten by it. It then |
83 | // can be taken into consideration during the put() method. |
84 | int fancy_upsampling; |
85 | |
86 | // Input buffer. |
87 | size_t data_size; |
88 | const uint8_t* data; |
89 | |
90 | // If true, in-loop filtering will not be performed even if present in the |
91 | // bitstream. Switching off filtering may speed up decoding at the expense |
92 | // of more visible blocking. Note that output will also be non-compliant |
93 | // with the VP8 specifications. |
94 | int bypass_filtering; |
95 | |
96 | // Cropping parameters. |
97 | int use_cropping; |
98 | int crop_left, crop_right, crop_top, crop_bottom; |
99 | |
100 | // Scaling parameters. |
101 | int use_scaling; |
102 | int scaled_width, scaled_height; |
103 | |
104 | // If non NULL, pointer to the alpha data (if present) corresponding to the |
105 | // start of the current row (That is: it is pre-offset by mb_y and takes |
106 | // cropping into account). |
107 | const uint8_t* a; |
108 | }; |
109 | |
110 | // Internal, version-checked, entry point |
111 | int VP8InitIoInternal(VP8Io* const, int); |
112 | |
113 | // Set the custom IO function pointers and user-data. The setter for IO hooks |
114 | // should be called before initiating incremental decoding. Returns true if |
115 | // WebPIDecoder object is successfully modified, false otherwise. |
116 | int WebPISetIOHooks(WebPIDecoder* const idec, |
117 | VP8IoPutHook put, |
118 | VP8IoSetupHook setup, |
119 | VP8IoTeardownHook teardown, |
120 | void* user_data); |
121 | |
122 | // Main decoding object. This is an opaque structure. |
123 | typedef struct VP8Decoder VP8Decoder; |
124 | |
125 | // Create a new decoder object. |
126 | VP8Decoder* VP8New(void); |
127 | |
128 | // Must be called to make sure 'io' is initialized properly. |
129 | // Returns false in case of version mismatch. Upon such failure, no other |
130 | // decoding function should be called (VP8Decode, VP8GetHeaders, ...) |
131 | static WEBP_INLINE int VP8InitIo(VP8Io* const io) { |
132 | return VP8InitIoInternal(io, WEBP_DECODER_ABI_VERSION); |
133 | } |
134 | |
135 | // Decode the VP8 frame header. Returns true if ok. |
136 | // Note: 'io->data' must be pointing to the start of the VP8 frame header. |
137 | int (VP8Decoder* const dec, VP8Io* const io); |
138 | |
139 | // Decode a picture. Will call VP8GetHeaders() if it wasn't done already. |
140 | // Returns false in case of error. |
141 | int VP8Decode(VP8Decoder* const dec, VP8Io* const io); |
142 | |
143 | // Return current status of the decoder: |
144 | VP8StatusCode VP8Status(VP8Decoder* const dec); |
145 | |
146 | // return readable string corresponding to the last status. |
147 | const char* VP8StatusMessage(VP8Decoder* const dec); |
148 | |
149 | // Resets the decoder in its initial state, reclaiming memory. |
150 | // Not a mandatory call between calls to VP8Decode(). |
151 | void VP8Clear(VP8Decoder* const dec); |
152 | |
153 | // Destroy the decoder object. |
154 | void VP8Delete(VP8Decoder* const dec); |
155 | |
156 | //------------------------------------------------------------------------------ |
157 | // Miscellaneous VP8/VP8L bitstream probing functions. |
158 | |
159 | // Returns true if the next 3 bytes in data contain the VP8 signature. |
160 | WEBP_EXTERN int VP8CheckSignature(const uint8_t* const data, size_t data_size); |
161 | |
162 | // Validates the VP8 data-header and retrieves basic header information viz |
163 | // width and height. Returns 0 in case of formatting error. *width/*height |
164 | // can be passed NULL. |
165 | WEBP_EXTERN int VP8GetInfo( |
166 | const uint8_t* data, |
167 | size_t data_size, // data available so far |
168 | size_t chunk_size, // total data size expected in the chunk |
169 | int* const width, int* const height); |
170 | |
171 | // Returns true if the next byte(s) in data is a VP8L signature. |
172 | WEBP_EXTERN int VP8LCheckSignature(const uint8_t* const data, size_t size); |
173 | |
174 | // Validates the VP8L data-header and retrieves basic header information viz |
175 | // width, height and alpha. Returns 0 in case of formatting error. |
176 | // width/height/has_alpha can be passed NULL. |
177 | WEBP_EXTERN int VP8LGetInfo( |
178 | const uint8_t* data, size_t data_size, // data available so far |
179 | int* const width, int* const height, int* const has_alpha); |
180 | |
181 | #ifdef __cplusplus |
182 | } // extern "C" |
183 | #endif |
184 | |
185 | #endif // WEBP_DEC_VP8_DEC_H_ |
186 | |