blob: 35c704b2f83af866e0106826ef01a3230fe779ba [file] [log] [blame]
// 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.
#include <stdint.h>
#include "media/base/bitstream_buffer.h"
#include "media/base/video_frame.h"
namespace chromeos_camera {
// 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 MjpegDecodeAccelerator {
// 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.
// Invalid argument was passed to an API method, e.g. the output buffer is
// too small, JPEG width/height are too big for JDA.
// Encoded input is unreadable, e.g. failed to map on another process.
// Failed to parse compressed JPEG picture.
// Failed to decode JPEG due to unsupported JPEG features, such as profiles,
// coding mode, or color formats.
// 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.
// Largest used enum. This should be adjusted when new errors are added.
class Client {
// 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;
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 output to |video_frame->format()| or return
// PLATFORM_FAILURE 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, backed
// with an UnsafeSharedMemoryRegion.
// Client is responsible for filling the |video_frame->coded_size()|,
// |video_frame->visible_rect()|, and allocating its backing buffer. For
// unsafe shared memory backed VideoFrames, only I420 format is supported.
// For DMA-buf backed VideoFrames, the supported formats depend on the
// underlying hardware implementation. 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(media::BitstreamBuffer bitstream_buffer,
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 chromeos_camera