media/video/jpeg_decode_accelerator.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_VIDEO_JPEG_DECODE_ACCELERATOR_H_
   6 #define MEDIA_VIDEO_JPEG_DECODE_ACCELERATOR_H_
   7
   8 #include "base/basictypes.h"
   9 #include "media/base/bitstream_buffer.h"
  10 #include "media/base/media_export.h"
  11 #include "media/base/video_frame.h"
  12
  13 namespace media {
  14
  15 // JPEG decoder interface.
  16 // The input are JPEG images including headers (Huffman tables may be omitted).
  17 // The output color format is I420. The decoder will convert the color format
  18 // to I420 if the color space or subsampling does not match that and if it is
  19 // capable of doing so. The client is responsible for allocating buffers and
  20 // keeps the ownership of them. All methods must be called on the same thread.
  21 // The intended use case of this interface is decoding MJPEG images coming
  22 // from camera capture. It can also be used for normal still JPEG image
  23 // decoding, but normal JPEG images may use more JPEG features that may not be
  24 // supported by a particular accelerator implementation and/or platform.
  25 class MEDIA_EXPORT JpegDecodeAccelerator {
  26  public:
  27   static const int32_t kInvalidBitstreamBufferId = -1;
  28
  29   // Enumeration of decode errors generated by NotifyError callback.
  30   enum Error {
  31     // Invalid argument was passed to an API method, e.g. the output buffer is
  32     // too small, JPEG width/height are too big for JDA.
  33     INVALID_ARGUMENT,
  34     // Encoded input is unreadable, e.g. failed to map on another process.
  35     UNREADABLE_INPUT,
  36     // Failed to parse compressed JPEG picture.
  37     PARSE_JPEG_FAILED,
  38     // Failed to decode JPEG due to unsupported JPEG features, such as profiles,
  39     // coding mode, or color formats.
  40     UNSUPPORTED_JPEG,
  41     // A fatal failure occurred in the GPU process layer or one of its
  42     // dependencies. Examples of such failures include hardware failures,
  43     // driver failures, library failures, browser programming errors, and so
  44     // on. Client is responsible for destroying JDA after receiving this.
  45     PLATFORM_FAILURE,
  46     // Largest used enum. This should be adjusted when new errors are added.
  47     LARGEST_ERROR_ENUM = PLATFORM_FAILURE,
  48   };
  49
  50   class MEDIA_EXPORT Client {
  51    public:
  52     // Callback called after each successful Decode().
  53     // Parameters:
  54     //  |bitstream_buffer_id| is the id of BitstreamBuffer corresponding to
  55     //  Decode() call.
  56     virtual void VideoFrameReady(int32_t bitstream_buffer_id) = 0;
  57
  58     // Callback to notify errors. Client is responsible for destroying JDA when
  59     // receiving a fatal error, i.e. PLATFORM_FAILURE. For other errors, client
  60     // is informed about the buffer that failed to decode and may continue
  61     // using the same instance of JDA.
  62     // Parameters:
  63     //  |error| is the error code.
  64     //  |bitstream_buffer_id| is the bitstream buffer id that resulted in the
  65     //  recoverable error. For PLATFORM_FAILURE, |bitstream_buffer_id| may be
  66     //  kInvalidBitstreamBufferId if the error was not related to any
  67     //  particular buffer being processed.
  68     virtual void NotifyError(int32_t bitstream_buffer_id, Error error) = 0;
  69
  70    protected:
  71     virtual ~Client() {}
  72   };
  73
  74   // JPEG decoder functions.
  75
  76   // Initializes the JPEG decoder. Should be called once per decoder
  77   // construction. This call is synchronous and returns true iff initialization
  78   // is successful.
  79   // Parameters:
  80   //  |client| is the Client interface for decode callback. The provided
  81   //  pointer must be valid until Destroy() is called.
  82   virtual bool Initialize(Client* client) = 0;
  83
  84   // Decodes the given bitstream buffer that contains one JPEG picture. It
  85   // supports at least baseline encoding defined in JPEG ISO/IEC 10918-1. The
  86   // decoder will convert the color format to I420 or return UNSUPPORTED_JPEG
  87   // if it cannot convert. Client still owns this buffer, but should deallocate
  88   // or access the buffer only after receiving a decode callback VideoFrameReady
  89   // with the corresponding bitstream_buffer_id, or NotifyError.
  90   // Parameters:
  91   //  |bitstream_buffer| contains encoded JPEG picture.
  92   //  |video_frame| contains an allocated video frame for the output.
  93   //  Client is responsible for filling the coded_size of video_frame and
  94   //  allocating its backing buffer. For now, only shared memory backed
  95   //  VideoFrames are supported. After decode completes, decoded JPEG picture
  96   //  will be filled into the |video_frame|.
  97   //  Ownership of the |bitstream_buffer| and |video_frame| remains with the
  98   //  client. The client is not allowed to deallocate them before
  99   //  VideoFrameReady or NotifyError() is invoked for given id of
 100   //  |bitstream_buffer|, or Destroy() returns.
 101   virtual void Decode(const BitstreamBuffer& bitstream_buffer,
 102                       const scoped_refptr<media::VideoFrame>& video_frame) = 0;
 103
 104   // Destroys the decoder: all pending inputs are dropped immediately. This
 105   // call may asynchronously free system resources, but its client-visible
 106   // effects are synchronous. After this method returns, no more callbacks
 107   // will be made on the client. Deletes |this| unconditionally, so make sure
 108   // to drop all pointers to it!
 109   virtual void Destroy() = 0;
 110
 111  protected:
 112   // Do not delete directly; use Destroy() or own it with a scoped_ptr, which
 113   // will Destroy() it properly by default.
 114   virtual ~JpegDecodeAccelerator();
 115 };
 116
 117 }  // namespace media
 118
 119 namespace base {
 120
 121 template <class T>
 122 struct DefaultDeleter;
 123
 124 // Specialize DefaultDeleter so that scoped_ptr<JpegDecodeAccelerator> always
 125 // uses "Destroy()" instead of trying to use the destructor.
 126 template <>
 127 struct MEDIA_EXPORT DefaultDeleter<media::JpegDecodeAccelerator> {
 128  public:
 129   void operator()(void* jpeg_decode_accelerator) const;
 130 };
 131
 132 }  // namespace base
 133
 134 #endif  // MEDIA_VIDEO_JPEG_DECODE_ACCELERATOR_H_