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