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)
18extern "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
40typedef struct VP8Io VP8Io;
41typedef int (*VP8IoPutHook)(const VP8Io* io);
42typedef int (*VP8IoSetupHook)(VP8Io* io);
43typedef void (*VP8IoTeardownHook)(const VP8Io* io);
44
45struct 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
109int 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.
114int 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.
121typedef struct VP8Decoder VP8Decoder;
122
123// Create a new decoder object.
124VP8Decoder* 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, ...)
129static 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.
134int 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.
138int VP8Decode(VP8Decoder* const dec, VP8Io* const io);
139
140// Return current status of the decoder:
141VP8StatusCode VP8Status(VP8Decoder* const dec);
142
143// return readable string corresponding to the last status.
144const 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().
148void VP8Clear(VP8Decoder* const dec);
149
150// Destroy the decoder object.
151void 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.
157WEBP_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.
162WEBP_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.
169WEBP_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.
174WEBP_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