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