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.
  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     // No error. Decode succeeded.
  32     NO_ERRORS,
  33     // Invalid argument was passed to an API method, e.g. the output buffer is
  34     // too small, JPEG width/height are too big for JDA.
  35     INVALID_ARGUMENT,
  36     // Encoded input is unreadable, e.g. failed to map on another process.
  37     UNREADABLE_INPUT,
  38     // Failed to parse compressed JPEG picture.
  39     PARSE_JPEG_FAILED,
  40     // Failed to decode JPEG due to unsupported JPEG features, such as profiles,
  41     // coding mode, or color formats.
  42     UNSUPPORTED_JPEG,
  43     // A fatal failure occurred in the GPU process layer or one of its
  44     // dependencies. Examples of such failures include hardware failures,
  45     // driver failures, library failures, browser programming errors, and so
  46     // on. Client is responsible for destroying JDA after receiving this.
  47     PLATFORM_FAILURE,
  48     // Largest used enum. This should be adjusted when new errors are added.
  49     LARGEST_ERROR_ENUM = PLATFORM_FAILURE,
  50   };
  51
  52   class MEDIA_EXPORT Client {
  53    public:
  54     // Callback called after each successful Decode().
  55     // Parameters:
  56     //  |bitstream_buffer_id| is the id of BitstreamBuffer corresponding to
  57     //  Decode() call.
  58     virtual void VideoFrameReady(int32_t bitstream_buffer_id) = 0;
  59
  60     // Callback to notify errors. Client is responsible for destroying JDA when
  61     // receiving a fatal error, i.e. PLATFORM_FAILURE. For other errors, client
  62     // is informed about the buffer that failed to decode and may continue
  63     // using the same instance of JDA.
  64     // Parameters:
  65     //  |error| is the error code.
  66     //  |bitstream_buffer_id| is the bitstream buffer id that resulted in the
  67     //  recoverable error. For PLATFORM_FAILURE, |bitstream_buffer_id| may be
  68     //  kInvalidBitstreamBufferId if the error was not related to any
  69     //  particular buffer being processed.
  70     virtual void NotifyError(int32_t bitstream_buffer_id, Error error) = 0;
  71
  72    protected:
  73     virtual ~Client() {}
  74   };
  75
  76   // Destroys the decoder: all pending inputs are dropped immediately. This
  77   // call may asynchronously free system resources, but its client-visible
  78   // effects are synchronous. After destructor returns, no more callbacks
  79   // will be made on the client.
  80   virtual ~JpegDecodeAccelerator() = 0;
  81
  82   // JPEG decoder functions.
  83
  84   // Initializes the JPEG decoder. Should be called once per decoder
  85   // construction. This call is synchronous and returns true iff initialization
  86   // is successful.
  87   // Parameters:
  88   //  |client| is the Client interface for decode callback. The provided
  89   //  pointer must be valid until destructor is called.
  90   virtual bool Initialize(Client* client) = 0;
  91
  92   // Decodes the given bitstream buffer that contains one JPEG picture. It
  93   // supports at least baseline encoding defined in JPEG ISO/IEC 10918-1. The
  94   // decoder will convert the color format to I420 or return UNSUPPORTED_JPEG
  95   // if it cannot convert. Client still owns this buffer, but should deallocate
  96   // or access the buffer only after receiving a decode callback VideoFrameReady
  97   // with the corresponding bitstream_buffer_id, or NotifyError.
  98   // Parameters:
  99   //  |bitstream_buffer| contains encoded JPEG picture.
 100   //  |video_frame| contains an allocated video frame for the output.
 101   //  Client is responsible for filling the coded_size of video_frame and
 102   //  allocating its backing buffer. For now, only shared memory backed
 103   //  VideoFrames are supported. After decode completes, decoded JPEG picture
 104   //  will be filled into the |video_frame|.
 105   //  Ownership of the |bitstream_buffer| and |video_frame| remains with the
 106   //  client. The client is not allowed to deallocate them before
 107   //  VideoFrameReady or NotifyError() is invoked for given id of
 108   //  |bitstream_buffer|, or destructor returns.
 109   virtual void Decode(const BitstreamBuffer& bitstream_buffer,
 110                       const scoped_refptr<media::VideoFrame>& video_frame) = 0;
 111 };
 112
 113 }  // namespace media
 114
 115 #endif  // MEDIA_VIDEO_JPEG_DECODE_ACCELERATOR_H_