Subversion Repositories Games.Descent

Rev

Blame | Last modification | View Log | Download | RSS feed

  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@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.   // 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.   uint32_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.   // pointer to the alpha data (if present) corresponding to the rows
  103.   const uint8_t* a;
  104. };
  105.  
  106. // Internal, version-checked, entry point
  107. WEBP_EXTERN(int) VP8InitIoInternal(VP8Io* const, int);
  108.  
  109. // Set the custom IO function pointers and user-data. The setter for IO hooks
  110. // should be called before initiating incremental decoding. Returns true if
  111. // WebPIDecoder object is successfully modified, false otherwise.
  112. WEBP_EXTERN(int) WebPISetIOHooks(WebPIDecoder* const idec,
  113.                                  VP8IoPutHook put,
  114.                                  VP8IoSetupHook setup,
  115.                                  VP8IoTeardownHook teardown,
  116.                                  void* user_data);
  117.  
  118. // Main decoding object. This is an opaque structure.
  119. typedef struct VP8Decoder VP8Decoder;
  120.  
  121. // Create a new decoder object.
  122. WEBP_EXTERN(VP8Decoder*) VP8New(void);
  123.  
  124. // Must be called to make sure 'io' is initialized properly.
  125. // Returns false in case of version mismatch. Upon such failure, no other
  126. // decoding function should be called (VP8Decode, VP8GetHeaders, ...)
  127. static WEBP_INLINE int VP8InitIo(VP8Io* const io) {
  128.   return VP8InitIoInternal(io, WEBP_DECODER_ABI_VERSION);
  129. }
  130.  
  131. // Start decoding a new picture. Returns true if ok.
  132. WEBP_EXTERN(int) VP8GetHeaders(VP8Decoder* const dec, VP8Io* const io);
  133.  
  134. // Decode a picture. Will call VP8GetHeaders() if it wasn't done already.
  135. // Returns false in case of error.
  136. WEBP_EXTERN(int) VP8Decode(VP8Decoder* const dec, VP8Io* const io);
  137.  
  138. // Return current status of the decoder:
  139. WEBP_EXTERN(VP8StatusCode) VP8Status(VP8Decoder* const dec);
  140.  
  141. // return readable string corresponding to the last status.
  142. WEBP_EXTERN(const char*) VP8StatusMessage(VP8Decoder* const dec);
  143.  
  144. // Resets the decoder in its initial state, reclaiming memory.
  145. // Not a mandatory call between calls to VP8Decode().
  146. WEBP_EXTERN(void) VP8Clear(VP8Decoder* const dec);
  147.  
  148. // Destroy the decoder object.
  149. WEBP_EXTERN(void) VP8Delete(VP8Decoder* const dec);
  150.  
  151. //------------------------------------------------------------------------------
  152.  
  153. #if defined(__cplusplus) || defined(c_plusplus)
  154. }    // extern "C"
  155. #endif
  156.  
  157. #endif  /* WEBP_WEBP_DECODE_VP8_H_ */
  158.