• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright 2010 Google Inc. All Rights Reserved.
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 "webp/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   size_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   // If non NULL, pointer to the alpha data (if present) corresponding to the
103   // start of the current row (That is: it is pre-offset by mb_y and takes
104   // cropping into account).
105   const uint8_t* a;
106 };
107 
108 // Internal, version-checked, entry point
109 int VP8InitIoInternal(VP8Io* const, int);
110 
111 // Set the custom IO function pointers and user-data. The setter for IO hooks
112 // should be called before initiating incremental decoding. Returns true if
113 // WebPIDecoder object is successfully modified, false otherwise.
114 int WebPISetIOHooks(WebPIDecoder* const idec,
115                     VP8IoPutHook put,
116                     VP8IoSetupHook setup,
117                     VP8IoTeardownHook teardown,
118                     void* user_data);
119 
120 // Main decoding object. This is an opaque structure.
121 typedef struct VP8Decoder VP8Decoder;
122 
123 // Create a new decoder object.
124 VP8Decoder* VP8New(void);
125 
126 // Must be called to make sure 'io' is initialized properly.
127 // Returns false in case of version mismatch. Upon such failure, no other
128 // decoding function should be called (VP8Decode, VP8GetHeaders, ...)
VP8InitIo(VP8Io * const io)129 static WEBP_INLINE int VP8InitIo(VP8Io* const io) {
130   return VP8InitIoInternal(io, WEBP_DECODER_ABI_VERSION);
131 }
132 
133 // Start decoding a new picture. Returns true if ok.
134 int VP8GetHeaders(VP8Decoder* const dec, VP8Io* const io);
135 
136 // Decode a picture. Will call VP8GetHeaders() if it wasn't done already.
137 // Returns false in case of error.
138 int VP8Decode(VP8Decoder* const dec, VP8Io* const io);
139 
140 // Return current status of the decoder:
141 VP8StatusCode VP8Status(VP8Decoder* const dec);
142 
143 // return readable string corresponding to the last status.
144 const char* VP8StatusMessage(VP8Decoder* const dec);
145 
146 // Resets the decoder in its initial state, reclaiming memory.
147 // Not a mandatory call between calls to VP8Decode().
148 void VP8Clear(VP8Decoder* const dec);
149 
150 // Destroy the decoder object.
151 void VP8Delete(VP8Decoder* const dec);
152 
153 //------------------------------------------------------------------------------
154 // Miscellaneous VP8/VP8L bitstream probing functions.
155 
156 // Returns true if the next 3 bytes in data contain the VP8 signature.
157 WEBP_EXTERN(int) VP8CheckSignature(const uint8_t* const data, size_t data_size);
158 
159 // Validates the VP8 data-header and retrieves basic header information viz
160 // width and height. Returns 0 in case of formatting error. *width/*height
161 // can be passed NULL.
162 WEBP_EXTERN(int) VP8GetInfo(
163     const uint8_t* data,
164     size_t data_size,    // data available so far
165     size_t chunk_size,   // total data size expected in the chunk
166     int* const width, int* const height);
167 
168 // Returns true if the next byte(s) in data is a VP8L signature.
169 WEBP_EXTERN(int) VP8LCheckSignature(const uint8_t* const data, size_t size);
170 
171 // Validates the VP8L data-header and retrieves basic header information viz
172 // width, height and alpha. Returns 0 in case of formatting error.
173 // width/height/has_alpha can be passed NULL.
174 WEBP_EXTERN(int) VP8LGetInfo(
175     const uint8_t* data, size_t data_size,  // data available so far
176     int* const width, int* const height, int* const has_alpha);
177 
178 #if defined(__cplusplus) || defined(c_plusplus)
179 }    // extern "C"
180 #endif
181 
182 #endif  /* WEBP_WEBP_DECODE_VP8_H_ */
183