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_WEBP_DECODE_VP8_H_
15#define WEBP_WEBP_DECODE_VP8_H_
16
17#include "../webp/decode.h"
18
19#ifdef __cplusplus
20extern "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//   bool ok = VP8Decode(dec);
37//   if (!ok) printf("Error: %s\n", VP8StatusMessage(dec));
38//   VP8Delete(dec);
39//   return ok;
40
41// Input / Output
42typedef struct VP8Io VP8Io;
43typedef int (*VP8IoPutHook)(const VP8Io* io);
44typedef int (*VP8IoSetupHook)(VP8Io* io);
45typedef void (*VP8IoTeardownHook)(const VP8Io* io);
46
47struct 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
111int 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.
116int 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.
123typedef struct VP8Decoder VP8Decoder;
124
125// Create a new decoder object.
126VP8Decoder* 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, ...)
131static 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.
137int 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.
141int VP8Decode(VP8Decoder* const dec, VP8Io* const io);
142
143// Return current status of the decoder:
144VP8StatusCode VP8Status(VP8Decoder* const dec);
145
146// return readable string corresponding to the last status.
147const 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().
151void VP8Clear(VP8Decoder* const dec);
152
153// Destroy the decoder object.
154void 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.
160WEBP_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.
165WEBP_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.
172WEBP_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.
177WEBP_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_WEBP_DECODE_VP8_H_ */
186