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, ...)
VP8InitIo(VP8Io * const io)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 VP8GetHeaders(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