Home | History | Annotate | Download | only in webp
      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