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