components/arc/common/video_encode_accelerator.mojom

// Copyright 2017 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.

// This file defined the mojo interface between Android and Chromium for video
// encoding.

module arc.mojom;

import "components/arc/common/video_common.mojom";

// Next MinVersion: 3

[Extensible]
enum VideoPixelFormat {
  // The values must match to the values in media::VideoPixelFormat
  PIXEL_FORMAT_UNKNOWN = 0,
  PIXEL_FORMAT_I420 = 1,
  [MinVersion=2] PIXEL_FORMAT_YV12 = 2,
  [MinVersion=2] PIXEL_FORMAT_NV12 = 6,
  [MinVersion=2] PIXEL_FORMAT_NV21 = 7,
  [MinVersion=2] PIXEL_FORMAT_ARGB = 10,
  [MinVersion=2] PIXEL_FORMAT_ABGR = 27,
  [MinVersion=2] PIXEL_FORMAT_XBGR = 28,
};

// Specification of an encoding profile supported by an encoder.
struct VideoEncodeProfile {
  VideoCodecProfile profile;
  Size max_resolution;
  uint32 max_framerate_numerator;
  uint32 max_framerate_denominator;
};


// The input buffer storage type.
[Extensible]
enum VideoFrameStorageType {
    SHMEM = 0,
    DMABUF = 1,
};

// The encoder parameter set which matches to
// media::VideoEncodeAccelerator::Config.
//  |input_format| is the pixel format of the input frames.
//  |input_visible_size| is the resolution of the input frames.
//  |output_profile| is the codec profile of the encoded output stream.
//  |initial_bitrate| is the initial bitrate of the encoded output stream,
//  in bits per second.
//  |initial_framerate| is the initial requested framerate. It is optional, only
//  valid when |has_initial_framerate| is true.
//  |h264_output_level| is H264 level of encoded output stream. It is optional,
//  only valid when |has_h264_output_level| is true.
//  |storage_type| is the storage type of video frame provided on Encode().
struct VideoEncodeAcceleratorConfig {
  VideoPixelFormat input_format;
  Size input_visible_size;
  VideoCodecProfile output_profile;
  uint32 initial_bitrate;
  uint32 initial_framerate;
  bool has_initial_framerate;
  uint8 h264_output_level;
  bool has_h264_output_level;
  [MinVersion=1] VideoFrameStorageType storage_type;
};

// Video encoder IPC interface.
// Next Method ID: 8
interface VideoEncodeAccelerator {
  // Enumeration of potential errors generated by the API.
  [Extensible]
  enum Error {
    // An operation was attempted during an incompatible encoder state.
    kIllegalStateError = 0,
    // Invalid argument was passed to an API method.
    kInvalidArgumentError = 1,
    // A failure occurred at the GPU process or one of its dependencies.
    // Examples of such failures include GPU hardware failures, GPU driver
    // failures, GPU library failures, GPU process programming errors, and so
    // on.
    kPlatformFailureError = 2,
    kErrorMax = kPlatformFailureError,
  };

  // Returns an array of the supported profiles of the video encoder. This can
  // be called before Initialize().
  GetSupportedProfiles@0() => (array<VideoEncodeProfile> profiles);

  // Initializes the video encoder with specific configuration.  Called once per
  // encoder construction.
  // Parameters:
  //  |config| is the parameter set for encoder initialization.
  //  |client| is the client of this video encoder. The client must be valid
  //  during the lifetime of this accelerator.
  // Callback:
  //  Called with true iff initialization is successful. The client should not
  //  invoke any other methods before the callback.
  [MinVersion=1]
  Initialize@7(VideoEncodeAcceleratorConfig config,
               VideoEncodeClient client) => (bool success);

  // Encodes the given frame.
  // Parameters:
  //  |frame_fd| is the handle of the video frame buffer. This could be the
  //  file descriptor of the shared memory or the dmabuf, depends on the
  //  storage type assigned in Initialize().
  //  |planes| is arrays of offset and stride of planes in the video frame.
  //  |timestamp| the timestamp of the video frame(in microseconds).
  //  |force_keyframe| forces the encoding of a keyframe for this frame.
  // Callback:
  //  Called when the frame has been processed and no longer used by this
  //  accelerator.
  Encode@2(handle frame_fd,
           array<VideoFramePlane> planes,
           int64 timestamp,
           bool force_keyframe) => ();

  // Sends a bitstream buffer to the encoder for storing encoded output. The
  // shared memory buffer will be filled with the encoded bitstream, and the
  // callback will be called.
  // Parameters:
  //  |bitstream_buffer_id| is the id of the bitstream buffer. It is used to
  //  identify the bitstream in VideoEncodeClient::BitstreamBufferReady().
  //  |shmem_fd| is the file descriptor of the shared memory.
  //  |offset| and |size| define the region in the shared memory to be used
  //  as the bitstream buffer.
  // Callback:
  //  Called when the encoded data has been filled in the bitstream buffer.
  //  |payload_size| is the byte size of the used portion of the buffer.
  //  |key_frame| is true if this delivered frame is a keyframe.
  //  |timestamp| is the same timestamp as the one passed to Encode().
  UseBitstreamBuffer@3(handle shmem_fd, uint32 offset, uint32 size)
      => (uint32 payload_size, bool key_frame, int64 timestamp);

  // Requests a change to the encoding parameters. This is only a request,
  // fulfilled on a best-effort basis.
  // Parameters:
  //  |bitrate| is the requested new bitrate, in bits per second.
  //  |framerate| is the requested new framerate, in frames per second.
  RequestEncodingParametersChange@4(uint32 bitrate,
                                    uint32 framerate);

  // Flushes the encoder: all pending inputs will be encoded and all bitstreams
  // handed back to the client. The client should not invoke Flush() or
  // Encode() before the previous Flush() is finished.
  // Callback:
  //  Called with |true| if Flush() is complete; with |false| if Flush() is
  //  canceled.
  Flush@5() => (bool flush_done);
};

// Interface for clients that use VideoEncodeAccelerator. These callbacks will
// not be made unless VideoEncodeAccelerator::Initialize() has returned
// successfully.
// Next MinVersion: 1
// Next Method ID: 3
interface VideoEncodeClient {
  // Callback to tell the client what size of frames and buffers to provide
  // for input and output. The VEA disclaims use or ownership of all previously
  // provided buffers once this callback is made.
  // Parameters:
  //  |input_count| is the number of input buffers required for encoding.
  //  The client should be prepared to feed at least this many frames into the
  //  encoder before being returned any input frames, since the encoder may
  //  need to hold onto some subset of inputs as reference pictures.
  //  |input_coded_size| is the logical size of the input frames, in pixels.
  //  The encoder may have hardware alignment requirements that make this
  //  different from |visible_size|, as requested in Initialize(), in which
  //  case the input video frame to Encode() should be padded appropriately.
  //  |output_buffer_size| is the required size of output buffers for this
  //  encoder in bytes.
  RequireBitstreamBuffers@0(uint32 input_count,
                            Size input_coded_size,
                            uint32 output_buffer_size);

  // Error notification callback. Note that errors in
  // VideoEncodeAccelerator::Initialize() will not be reported here, but will
  // instead be indicated by a false return value there.
  NotifyError@2(VideoEncodeAccelerator.Error error);
};