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 (at) 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 20 extern "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 42 typedef struct VP8Io VP8Io; 43 typedef int (*VP8IoPutHook)(const VP8Io* io); 44 typedef int (*VP8IoSetupHook)(VP8Io* io); 45 typedef void (*VP8IoTeardownHook)(const VP8Io* io); 46 47 struct 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 111 int 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. 116 int 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. 123 typedef struct VP8Decoder VP8Decoder; 124 125 // Create a new decoder object. 126 VP8Decoder* 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, ...) 131 static 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. 137 int 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. 141 int VP8Decode(VP8Decoder* const dec, VP8Io* const io); 142 143 // Return current status of the decoder: 144 VP8StatusCode VP8Status(VP8Decoder* const dec); 145 146 // return readable string corresponding to the last status. 147 const 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(). 151 void VP8Clear(VP8Decoder* const dec); 152 153 // Destroy the decoder object. 154 void 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. 160 WEBP_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. 165 WEBP_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. 172 WEBP_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. 177 WEBP_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
