media/mojo/mojom/video_encode_accelerator.mojom

   1 // Copyright 2017 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 module media.mojom;
   6
   7 import "media/mojo/mojom/media_log.mojom";
   8 import "media/mojo/mojom/media_types.mojom";
   9 import "mojo/public/mojom/base/shared_memory.mojom";
  10 import "mojo/public/mojom/base/time.mojom";
  11 import "ui/gfx/geometry/mojom/geometry.mojom";
  12 import "ui/gfx/mojom/color_space.mojom";
  13 import "media/mojo/mojom/video_encoder_info.mojom";
  14 import "sandbox/policy/mojom/sandbox.mojom";
  15
  16 // This file is the Mojo version of the media::VideoEncodeAccelerator interface
  17 // and describes the communication between a Client and a remote "service"
  18 // VideoEncodeAccelerator (VEA) with the purpose of encoding Video Frames by
  19 // means of hardware accelerated features.
  20 //
  21 //   Client                                    VideoEncodeAccelerator
  22 //      | ---> Initialize                                       |
  23 //      |                     RequireBitstreamBuffers(N) <---   |
  24 //      | ---> UseOutputBitstreamBuffer(0)                      |
  25 //      | ---> UseOutputBitstreamBuffer(1)                      |
  26 //      |  ...                                                  |
  27 //      =                                                       =
  28 // The Client requests a remote Encode() and eventually the VEA will leave the
  29 // encoded results in a pre-shared BitstreamBuffer, that is then restored to the
  30 // VEA when the Client is finished with it. Note that there might not be a 1:1
  31 // relationship between Encode() and BitstreamBufferReady() calls.
  32 //      | ---> Encode()                                         |
  33 //      |                        BitstreamBufferReady(k) <---   |
  34 //      | ---> UseOutputBitstreamBuffer(k)                      |
  35 //      =                                                       =
  36 // At any time the VEA can send a NotifyError() to the Client. Similarly at any
  37 // time the Client can send a RequestEncodingParametersChange() to the VEA. None
  38 // of these messages are acknowledged.
  39
  40
  41 enum VideoEncodeAcceleratorSupportedRateControlMode {
  42   kNoMode,
  43   kConstantMode,
  44   kVariableMode,
  45   kExternalMode
  46 };
  47
  48 struct VideoEncodeAcceleratorSupportedProfile {
  49   VideoCodecProfile profile;
  50   gfx.mojom.Size min_resolution;
  51   gfx.mojom.Size max_resolution;
  52   uint32 max_framerate_numerator;
  53   uint32 max_framerate_denominator;
  54   array<VideoEncodeAcceleratorSupportedRateControlMode> rate_control_modes;
  55   array<SVCScalabilityMode> scalability_modes;
  56   bool is_software_codec;
  57 };
  58
  59 // A renderer process calls this interface's functions. GPU process implements
  60 // this interface.
  61 interface VideoEncodeAcceleratorProvider {
  62   // Creates a VideoEncodeAccelerator bound to |receiver|.
  63   CreateVideoEncodeAccelerator(
  64         pending_receiver<VideoEncodeAccelerator> receiver);
  65
  66   // Get a VideoEncodeAccelerator supported profiles.
  67   GetVideoEncodeAcceleratorSupportedProfiles()
  68       => (array<VideoEncodeAcceleratorSupportedProfile> profiles);
  69 };
  70
  71 // This interface allows the browser process to broker
  72 // VideoEncodeAcceleratorProvider connection requests on behalf of a renderer.
  73 // The browser creates the mojo pipe and gives the receiver to a utility
  74 // process. The expected usage is as follows:
  75 //
  76 // 1) The browser process receives a request from a renderer process to bind a
  77 //    pending_receiver<VideoEncodeAcceleratorProvider>.
  78 //
  79 // 2) To satisfy that request, the browser process first starts a utility
  80 //    process that hosts a VideoEncodeAcceleratorProviderFactory if it hasn't
  81 //    already done so -- note that each renderer process should get its own
  82 //    corresponding utility process.
  83 //
  84 // 3) The browser process calls CreateVideoEncodeAcceleratorProvider() passing
  85 //    the pending_receiver<VideoEncodeAcceleratorProvider> received from the
  86 //    renderer process.
  87 [EnableIf=is_linux_or_chromeos,
  88 ServiceSandbox=sandbox.mojom.Sandbox.kHardwareVideoEncoding]
  89 interface VideoEncodeAcceleratorProviderFactory {
  90   // Creates a VideoEncodeAcceleratorProvider and should be called by the
  91   // browser process.
  92   CreateVideoEncodeAcceleratorProvider(
  93         pending_receiver<VideoEncodeAcceleratorProvider> receiver);
  94 };
  95
  96 // This defines a mojo transport format used in the
  97 // mojo::VideoBitrateAllocation that corresponds to media::Bitrate::peak_bps_
  98 struct VariableBitratePeak {
  99   uint32 bps;
 100 };
 101
 102 // Class that describes how video bitrate, in bps, is allocated across temporal
 103 // and spatial layers. See media::VideoBitrateAllocation for more details.
 104 struct VideoBitrateAllocation {
 105   array<uint32> bitrates;
 106   VariableBitratePeak? variable_bitrate_peak;
 107 };
 108
 109 // This defines a mojo transport format for
 110 // media::VideoEncodeAccelerator::Config::SpatialLayer.
 111 struct SpatialLayer {
 112   int32 width;
 113   int32 height;
 114   uint32 bitrate_bps;
 115   uint32 framerate;
 116   uint8 max_qp;
 117   uint8 num_of_temporal_layers;
 118 };
 119
 120 // This defines a mojo transport format for a media::Bitrate of type kConstant.
 121 // The default target here matches that in media::Bitrate.
 122 struct ConstantBitrate {
 123   uint32 target_bps = 0;
 124 };
 125
 126 // This defines a mojo transport format for a media::Bitrate of type kVariable.
 127 // The default target here matches that in media::Bitrate.
 128 struct VariableBitrate {
 129   uint32 target_bps = 0;
 130   uint32 peak_bps;
 131 };
 132
 133 struct ExternalBitrate {
 134 };
 135
 136 // This defines a mojo transport format for media::Bitrate.
 137 union Bitrate {
 138   ConstantBitrate constant;
 139   VariableBitrate variable;
 140   ExternalBitrate external;
 141 };
 142
 143 // This defines a mojo transport format for
 144 // media::VideoEncodeAccelerator::Config.
 145 struct VideoEncodeAcceleratorConfig {
 146   // See media::VideoEncodeAccelerator::Config::ContentType
 147   enum ContentType {
 148     kCamera,
 149     kDisplay
 150   };
 151
 152   // See media::VideoEncodeAccelerator::Config::StorageType
 153   enum StorageType {
 154     kShmem,
 155     kGpuMemoryBuffer,
 156   };
 157
 158   // See media::VideoEncodeAccelerator::Config::EncoderType
 159   enum EncoderType {
 160     kHardware,
 161     kSoftware,
 162     kNoPreference,
 163   };
 164
 165   VideoPixelFormat input_format;
 166   gfx.mojom.Size input_visible_size;
 167   VideoCodecProfile output_profile;
 168   Bitrate bitrate;
 169   uint32 initial_framerate;
 170   bool has_initial_framerate;  // Whether or not config has initial framerate
 171   uint32 gop_length;
 172   bool has_gop_length;  // Whether or not config has group of picture length
 173   uint8 h264_output_level;
 174   bool has_h264_output_level;  // Whether or not config has H264 output level
 175   bool is_constrained_h264;
 176   StorageType storage_type;
 177   bool has_storage_type;  // Whether or not config has storage type config
 178   ContentType content_type;
 179   array<SpatialLayer> spatial_layers;
 180   SVCInterLayerPredMode inter_layer_pred;
 181   bool require_low_delay;
 182   EncoderType required_encoder_type;
 183 };
 184
 185 // Options for encoding a single frame by VideoEncodeAccelerator.
 186 // This defines a mojo transport format for a
 187 // media::VideoEncoder::EncodeOptions.
 188 struct VideoEncodeOptions {
 189   // If True, next frame must be encoded as I-frame (random access point)
 190   bool force_keyframe;
 191
 192   // Quantizer(QP) value for encoding of the given frame.
 193   // This value is only heeded if VEA configured with external rate control mode
 194   // TODO(crbug.com/657632): All negative values mean "ignore this field",
 195   // we don't use proper optional field because Java bindgen doesn't support
 196   // optional primitive types.
 197   int32 quantizer;
 198 };
 199
 200 // The interface to access the hardware video encoding accelerator.
 201 interface VideoEncodeAccelerator {
 202   // Responded by VideoEncodeAcceleratorClient.RequireBitstreamBuffers().
 203   [Sync]
 204   Initialize(VideoEncodeAcceleratorConfig config,
 205              pending_associated_remote<VideoEncodeAcceleratorClient> client,
 206              pending_remote<MediaLog> media_log)
 207       => (bool result);
 208
 209   // Encodes a |frame|, being completely done with it after its callback.
 210   Encode(VideoFrame frame, VideoEncodeOptions options) => ();
 211
 212   UseOutputBitstreamBuffer(int32 bitstream_buffer_id,
 213                            mojo_base.mojom.UnsafeSharedMemoryRegion region);
 214
 215   // Request a change to the encoding parameters.
 216   // This method is intended for use with spatial or temporal layers,
 217   // and is implicitly a constant bitrate encoding.
 218   // Parameters:
 219   //  |bitrate_allocation| is the requested new bitrate, per spatial and
 220   //                       temporal layer.
 221   //  |framerate| is the requested new framerate, in frames per second.
 222   RequestEncodingParametersChangeWithLayers(
 223     VideoBitrateAllocation bitrate_allocation,
 224     uint32 framerate);
 225
 226   // Request a change to the encoding parameters. This method is for use
 227   // with non-layered bitrates, and may make requests for constant or
 228   // variable bitrates based on the initially-configured bitrate mode.
 229   // Parameters:
 230   //  |bitrate| is the requested new bitrate for non-layered encoding, which
 231   //            may be constant or variable bitrate. This should not change the
 232   //            encoding mode (constant -> variable or variable -> constant).
 233   //  |framerate| is the requested new framerate, in frames per second.
 234   RequestEncodingParametersChangeWithBitrate(
 235     Bitrate bitrate,
 236     uint32 framerate);
 237
 238   [Sync]
 239   IsFlushSupported() => (bool result);
 240
 241   Flush() => (bool result);
 242 };
 243
 244 // H264Metadata, H265metadata, Vp8Metadata, Vp9Metadata and Av1Metadata define
 245 // mojo transport formats for media::H264Metadata, H265Metadata,
 246 // media::Vp8Metadata, media::Vp9Metadata and media::Av1Metadata, respectively.
 247 // See the structures defined video_encode_accelerator.h for the descriptions of
 248 // the variables.
 249 // Either of them is filled in GPU process only in the case of temporal/spatial
 250 // SVC encoding. That is, none of them is filled in the case of non
 251 // temporal/spatial SVC encoding. Thus CodecMetadata is union and CodecMetadata
 252 // exists as optional in BitstreamBufferMetadata.
 253 // BitstreamBufferMetadata is metadata about a bitstream buffer produced by a
 254 // hardware encoder. The structure is passed from GPU process to renderer
 255 // process in BitstreamBufferReady() call.
 256 struct H264Metadata {
 257   uint8 temporal_idx;
 258   bool layer_sync;
 259 };
 260
 261 struct H265Metadata {
 262   uint8 temporal_idx;
 263 };
 264
 265 struct Vp8Metadata {
 266   bool non_reference;
 267   uint8 temporal_idx;
 268   bool layer_sync;
 269 };
 270
 271 struct Vp9Metadata {
 272   bool inter_pic_predicted;
 273   bool temporal_up_switch;
 274   bool referenced_by_upper_spatial_layers;
 275   bool reference_lower_spatial_layers;
 276   bool end_of_picture;
 277   uint8 temporal_idx;
 278   uint8 spatial_idx;
 279   array<gfx.mojom.Size> spatial_layer_resolutions;
 280   uint8 begin_active_spatial_layer_index;
 281   uint8 end_active_spatial_layer_index;
 282   array<uint8> p_diffs;
 283 };
 284
 285 struct Av1Metadata {
 286   uint8 temporal_idx;
 287 };
 288
 289 // Codec specific metadata.
 290 union CodecMetadata {
 291   H264Metadata h264;
 292   H265Metadata h265;
 293   Vp8Metadata vp8;
 294   Vp9Metadata vp9;
 295   Av1Metadata av1;
 296 };
 297
 298 struct BitstreamBufferMetadata {
 299   uint32 payload_size_bytes;
 300   bool key_frame;
 301   mojo_base.mojom.TimeDelta timestamp;
 302   int32 qp;
 303   CodecMetadata? codec_metadata;
 304   gfx.mojom.Size? encoded_size;
 305   gfx.mojom.ColorSpace? encoded_color_space;
 306 };
 307
 308 interface VideoEncodeAcceleratorClient {
 309   // Response to VideoEncodeAccelerator.Initialize().
 310   RequireBitstreamBuffers(uint32 input_count,
 311                           gfx.mojom.Size input_coded_size,
 312                           uint32 output_buffer_size);
 313
 314   BitstreamBufferReady(int32 bitstream_buffer_id,
 315                        BitstreamBufferMetadata metadata);
 316   // VideoEncodeAccelerator calls this when the error occurs and it cannot
 317   // perform encoding any more. |status| represents the detail about the error.
 318   NotifyErrorStatus(EncoderStatus status);
 319
 320   // VideoEncodeAccelerator calls this when its VideoEncoderInfo is changed.
 321   // |info| is the updated VideoEncoderInfo.
 322   NotifyEncoderInfoChange(VideoEncoderInfo info);
 323 };