ash / components / arc / mojom / video_encode_accelerator.mojom [blame]

// Copyright 2017 The Chromium Authors
// 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 "ash/components/arc/mojom/gfx.mojom";
import "ash/components/arc/mojom/video_common.mojom";
import "sandbox/policy/mojom/sandbox.mojom";

// Next MinVersion: 6

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

// Constant bitrate type, used for constant bitrate encoding.
//  |target| is the desired output bitrate.
struct ConstantBitrate {
  uint32 target;
};

// Variable bitrate type, used for variable bitrate encoding.
//  |target| is the desired output bitrate.
//  |peak| is the maximum output bitrate.
struct VariableBitrate {
  uint32 target;
  uint32 peak;
};

// Bitrate type, can either be constant (CBR) or variable (VBR).
//  |constant| constant bitrate mode, only target can be configured.
//  |variable| variable bitrate mode, both target and peak can be configured.
union Bitrate {
  ConstantBitrate constant;
  VariableBitrate variable;
};

// The encoder parameter set which matches to
// media::VideoEncodeAccelerator::Config except |is_constrained_h264| parameter
// which is a flag for H264 profile.
//  |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_deprecated| is the initial bitrate of the encoded output
//  stream, in bits per second. This field has been deprecated and should be
//  removed in favor of |bitrate|.
//  |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().
//  |bitrate| contains the desired bitrate mode (CBR/VBR), target bitrate and
//  peak bitrate (only applicable if using variable bitrate mode).
struct VideoEncodeAcceleratorConfig {
  VideoPixelFormat input_format;
  Size input_visible_size;
  VideoCodecProfile output_profile;
  // TODO(b/325160191): Sync mojom files in ARC/ARCVM side and remove these
  // variables.
  uint32 initial_bitrate_deprecated;
  uint32 initial_framerate;
  bool has_initial_framerate_deprecated;
  uint8 h264_output_level;
  bool has_h264_output_level;
  [MinVersion=1] VideoFrameStorageType storage_type;
  [MinVersion=5] Bitrate? bitrate;
};

// Video encoder IPC interface.
// Deprecated method IDs: 4, 7
// Next Method ID: 11
[ServiceSandbox=sandbox.mojom.Sandbox.kGpu]
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,
  };

  enum Result {
    kSuccess = 0,
    kIllegalStateError = 1,
    kInvalidArgumentError = 2,
    kPlatformFailureError = 3,
    kInsufficientResourcesError = 4,
  };

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

  [MinVersion=4]
  Initialize@9(VideoEncodeAcceleratorConfig config,
               pending_remote<VideoEncodeClient> client) => (Result result);

  // Encodes the given frame.
  // Parameters:
  //  |format| is the pixel format of video frame. This could be different from
  //  pixel format configured on Initialize().
  //  |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.
  [MinVersion=3]
  Encode@8(VideoPixelFormat format,
           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 target and peak bitrate. The bitrate mode
  //  should not be changed during encoding.
  //  |framerate| is the requested new framerate, in frames per second.
  [MinVersion=5]
  RequestEncodingParametersChange@10(Bitrate bitrate, uint32 framerate);

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