media/video/mjpeg_decode_accelerator.h

// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef MEDIA_VIDEO_MJPEG_DECODE_ACCELERATOR_H_
#define MEDIA_VIDEO_MJPEG_DECODE_ACCELERATOR_H_

#include <stdint.h>

#include "media/base/bitstream_buffer.h"
#include "media/base/media_export.h"
#include "media/base/video_frame.h"

namespace media {

// MJPEG decoder interface.
// The input are JPEG images including headers (Huffman tables may be omitted).
// The output color format is I420. The decoder will convert the color format
// to I420 if the color space or subsampling does not match that and if it is
// capable of doing so. The client is responsible for allocating buffers and
// keeps the ownership of them.
// The intended use case of this interface is decoding MJPEG images coming
// from camera capture. It can also be used for normal still JPEG image
// decoding, but normal JPEG images may use more JPEG features that may not be
// supported by a particular accelerator implementation and/or platform.
class MEDIA_EXPORT MjpegDecodeAccelerator {
 public:
  // Callback for JPEG decoder initialization.
  typedef base::Callback<void(bool success)> InitCB;

  static const int32_t kInvalidBitstreamBufferId = -1;

  // Enumeration of decode errors generated by NotifyError callback. These
  // values are persisted to logs. Entries should not be renumbered and numeric
  // values should never be reused.
  enum Error {
    // No error. Decode succeeded.
    NO_ERRORS = 0,
    // Invalid argument was passed to an API method, e.g. the output buffer is
    // too small, JPEG width/height are too big for JDA.
    INVALID_ARGUMENT = 1,
    // Encoded input is unreadable, e.g. failed to map on another process.
    UNREADABLE_INPUT = 2,
    // Failed to parse compressed JPEG picture.
    PARSE_JPEG_FAILED = 3,
    // Failed to decode JPEG due to unsupported JPEG features, such as profiles,
    // coding mode, or color formats.
    UNSUPPORTED_JPEG = 4,
    // A fatal failure occurred in the GPU process layer or one of its
    // dependencies. Examples of such failures include hardware failures,
    // driver failures, library failures, browser programming errors, and so
    // on. Client is responsible for destroying JDA after receiving this.
    PLATFORM_FAILURE = 5,
    // Largest used enum. This should be adjusted when new errors are added.
    MJDA_ERROR_CODE_MAX = PLATFORM_FAILURE,
  };

  class MEDIA_EXPORT Client {
   public:
    // Callback called after each successful Decode().
    // Parameters:
    //  |bitstream_buffer_id| is the id of BitstreamBuffer corresponding to
    //  Decode() call.
    virtual void VideoFrameReady(int32_t bitstream_buffer_id) = 0;

    // Callback to notify errors. Client is responsible for destroying JDA when
    // receiving a fatal error, i.e. PLATFORM_FAILURE. For other errors, client
    // is informed about the buffer that failed to decode and may continue
    // using the same instance of JDA.
    // Parameters:
    //  |error| is the error code.
    //  |bitstream_buffer_id| is the bitstream buffer id that resulted in the
    //  recoverable error. For PLATFORM_FAILURE, |bitstream_buffer_id| may be
    //  kInvalidBitstreamBufferId if the error was not related to any
    //  particular buffer being processed.
    virtual void NotifyError(int32_t bitstream_buffer_id, Error error) = 0;

   protected:
    virtual ~Client() {}
  };

  // Destroys the decoder: all pending inputs are dropped immediately. This
  // call may asynchronously free system resources, but its client-visible
  // effects are synchronous. After destructor returns, no more callbacks
  // will be made on the client.
  virtual ~MjpegDecodeAccelerator() = 0;

  // Initializes the MJPEG decoder. Should be called once per decoder
  // construction. This call is synchronous and returns true iff initialization
  // is successful.
  // Parameters:
  //  |client| is the Client interface for decode callback. The provided
  //  pointer must be valid until destructor is called.
  virtual bool Initialize(Client* client) = 0;

  // TODO(c.padhi): Remove the sync version and rename this to Initialize.
  // Async version of above Initialize(..) function. Executes the |init_cb|
  // upon completion.
  virtual void InitializeAsync(Client* client, InitCB init_cb) {}

  // Decodes the given bitstream buffer that contains one JPEG frame. It
  // supports at least baseline encoding defined in JPEG ISO/IEC 10918-1. The
  // decoder will convert the color format to I420 or return UNSUPPORTED_JPEG
  // if it cannot convert. Client still owns this buffer, but should deallocate
  // or access the buffer only after receiving a decode callback VideoFrameReady
  // with the corresponding bitstream_buffer_id, or NotifyError.
  // Parameters:
  //  |bitstream_buffer| contains encoded JPEG frame.
  //  |video_frame| contains an allocated video frame for the output.
  //  Client is responsible for filling the coded_size of video_frame and
  //  allocating its backing buffer. For now, only shared memory backed
  //  VideoFrames are supported. After decode completes, the decoded JPEG frame
  //  will be filled into the |video_frame|.
  //  Ownership of the |bitstream_buffer| and |video_frame| remains with the
  //  client. The client is not allowed to deallocate them before
  //  VideoFrameReady or NotifyError() is invoked for given id of
  //  |bitstream_buffer|, or destructor returns.
  virtual void Decode(const BitstreamBuffer& bitstream_buffer,
                      const scoped_refptr<media::VideoFrame>& video_frame) = 0;

  // Returns true when the JPEG decoder is supported. This can be called before
  // Initialize().
  virtual bool IsSupported() = 0;
};

}  // namespace media

#endif  // MEDIA_VIDEO_MJPEG_DECODE_ACCELERATOR_H_