1 // Copyright 2010 Google Inc. 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 (at) gmail.com) 11 12 #ifndef WEBP_WEBP_DECODE_VP8_H_ 13 #define WEBP_WEBP_DECODE_VP8_H_ 14 15 #include "./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 // Should returns 0 in case of error. 71 VP8IoSetupHook setup; 72 73 // called just after block decoding is finished (or when an error occurred). 74 VP8IoTeardownHook teardown; 75 76 // this is a recommendation for the user-side yuv->rgb converter. This flag 77 // is set when calling setup() hook and can be overwritten by it. It then 78 // can be taken into consideration during the put() method. 79 int fancy_upsampling; 80 81 // Input buffer. 82 uint32_t data_size; 83 const uint8_t* data; 84 85 // If true, in-loop filtering will not be performed even if present in the 86 // bitstream. Switching off filtering may speed up decoding at the expense 87 // of more visible blocking. Note that output will also be non-compliant 88 // with the VP8 specifications. 89 int bypass_filtering; 90 91 // Cropping parameters. 92 int use_cropping; 93 int crop_left, crop_right, crop_top, crop_bottom; 94 95 // Scaling parameters. 96 int use_scaling; 97 int scaled_width, scaled_height; 98 99 // pointer to the alpha data (if present) corresponding to the rows 100 const uint8_t* a; 101 }; 102 103 // Internal, version-checked, entry point 104 WEBP_EXTERN(int) VP8InitIoInternal(VP8Io* const, int); 105 106 // Set the custom IO function pointers and user-data. The setter for IO hooks 107 // should be called before initiating incremental decoding. Returns true if 108 // WebPIDecoder object is successfully modified, false otherwise. 109 WEBP_EXTERN(int) WebPISetIOHooks(WebPIDecoder* const idec, 110 VP8IoPutHook put, 111 VP8IoSetupHook setup, 112 VP8IoTeardownHook teardown, 113 void* user_data); 114 115 // Main decoding object. This is an opaque structure. 116 typedef struct VP8Decoder VP8Decoder; 117 118 // Create a new decoder object. 119 WEBP_EXTERN(VP8Decoder*) VP8New(void); 120 121 // Must be called to make sure 'io' is initialized properly. 122 // Returns false in case of version mismatch. Upon such failure, no other 123 // decoding function should be called (VP8Decode, VP8GetHeaders, ...) 124 static inline int VP8InitIo(VP8Io* const io) { 125 return VP8InitIoInternal(io, WEBP_DECODER_ABI_VERSION); 126 } 127 128 // Start decoding a new picture. Returns true if ok. 129 WEBP_EXTERN(int) VP8GetHeaders(VP8Decoder* const dec, VP8Io* const io); 130 131 // Decode a picture. Will call VP8GetHeaders() if it wasn't done already. 132 // Returns false in case of error. 133 WEBP_EXTERN(int) VP8Decode(VP8Decoder* const dec, VP8Io* const io); 134 135 // Return current status of the decoder: 136 WEBP_EXTERN(VP8StatusCode) VP8Status(VP8Decoder* const dec); 137 138 // return readable string corresponding to the last status. 139 WEBP_EXTERN(const char*) VP8StatusMessage(VP8Decoder* const dec); 140 141 // Resets the decoder in its initial state, reclaiming memory. 142 // Not a mandatory call between calls to VP8Decode(). 143 WEBP_EXTERN(void) VP8Clear(VP8Decoder* const dec); 144 145 // Destroy the decoder object. 146 WEBP_EXTERN(void) VP8Delete(VP8Decoder* const dec); 147 148 //----------------------------------------------------------------------------- 149 150 #if defined(__cplusplus) || defined(c_plusplus) 151 } // extern "C" 152 #endif 153 154 #endif /* WEBP_WEBP_DECODE_VP8_H_ */ 155
