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 "video_common.mojom";

[Extensible]
enum VideoPixelFormat {
  // The values must match to the values in media::VideoPixelFormat
  PIXEL_FORMAT_UNKNOWN = 0,
  PIXEL_FORMAT_I420 = 1,
};

[Extensible]
enum VideoCodecProfile {
  // The values must match to the values in media::VideoCodecProfile.
  VIDEO_CODEC_PROFILE_UNKNOWN = -1,
  VIDEO_CODEC_PROFILE_MIN = VIDEO_CODEC_PROFILE_UNKNOWN,
  H264PROFILE_MIN = 0,

  // Including profile Constrained Baseline (CBP).
  H264PROFILE_BASELINE = H264PROFILE_MIN,
  H264PROFILE_MAIN = 1,
  H264PROFILE_EXTENDED = 2,
  H264PROFILE_HIGH = 3,
  H264PROFILE_HIGH10PROFILE = 4,
  H264PROFILE_HIGH422PROFILE = 5,
  H264PROFILE_HIGH444PREDICTIVEPROFILE = 6,
  H264PROFILE_SCALABLEBASELINE = 7,
  H264PROFILE_SCALABLEHIGH = 8,
  H264PROFILE_STEREOHIGH = 9,
  H264PROFILE_MULTIVIEWHIGH = 10,
  H264PROFILE_MAX = H264PROFILE_MULTIVIEWHIGH,
  VP8PROFILE_MIN = 11,
  VP8PROFILE_ANY = VP8PROFILE_MIN,
  VP8PROFILE_MAX = VP8PROFILE_ANY,
  VP9PROFILE_MIN = 12,
  VP9PROFILE_PROFILE0 = VP9PROFILE_MIN,
  VP9PROFILE_PROFILE1 = 13,
  VP9PROFILE_PROFILE2 = 14,
  VP9PROFILE_PROFILE3 = 15,
  VP9PROFILE_MAX = VP9PROFILE_PROFILE3,
  HEVCPROFILE_MIN = 16,
  HEVCPROFILE_MAIN = HEVCPROFILE_MIN,
  HEVCPROFILE_MAIN10 = 17,
  HEVCPROFILE_MAIN_STILL_PICTURE = 18,
  HEVCPROFILE_MAX = HEVCPROFILE_MAIN_STILL_PICTURE,
  DOLBYVISION_MIN = 19,
  DOLBYVISION_PROFILE0 = DOLBYVISION_MIN,
  DOLBYVISION_PROFILE4 = 20,
  DOLBYVISION_PROFILE5 = 21,
  DOLBYVISION_PROFILE7 = 22,
  DOLBYVISION_MAX = DOLBYVISION_PROFILE7,
  THEORAPROFILE_MIN = 23,
  THEORAPROFILE_ANY = THEORAPROFILE_MIN,
  THEORAPROFILE_MAX = THEORAPROFILE_ANY,
  VIDEO_CODEC_PROFILE_MAX = THEORAPROFILE_ANY,
};

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

// Video encoder IPC interface.
// Next MinVersion: 1
// Next Method ID: 5
interface VideoEncodeAccelerator {

  // The input buffer storage type.
  [Extensible]
  enum StorageType {
    SHARED_MEMORY,
    DMABUF,
  };

  // 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:
  //  |input_format| is the pixel format of the input frames.
  //  |visible_size| is the resolution of the input frames.
  //  |input_storage| the type of the input buffer.
  //  |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.
  //  |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.
  Initialize@1(VideoPixelFormat input_format,
               Size visible_size,
               StorageType input_storage,
               VideoCodecProfile output_profile,
               uint32 initial_bitrate,
               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);
};

// 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);
};