media/mojo/mojom/video_decoder.mojom

   1 // Copyright 2016 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 "gpu/ipc/common/sync_token.mojom";
   8 import "media/mojo/mojom/media_log.mojom";
   9 import "media/mojo/mojom/media_types.mojom";
  10 import "mojo/public/mojom/base/unguessable_token.mojom";
  11 import "ui/gfx/geometry/mojom/geometry.mojom";
  12 import "ui/gfx/mojom/color_space.mojom";
  13
  14 // Serializable rule for matching VideoDecoderConfigs.
  15 struct SupportedVideoDecoderConfig {
  16   // Range of VideoCodecProfiles to match, inclusive.
  17   VideoCodecProfile profile_min;
  18   VideoCodecProfile profile_max;
  19
  20   // Range of coded sizes to match, inclusive in each dimension.
  21   gfx.mojom.Size coded_size_min;
  22   gfx.mojom.Size coded_size_max;
  23
  24   // Match configs that have encryption configured.
  25   bool allow_encrypted;
  26
  27   // Do not match configs that do not have encryption configured. This is used
  28   // on Android when the internal software decoder is preferred over the
  29   // platform decoder (eg. when the platform decoder is a software decoder).
  30   bool require_encrypted;
  31 };
  32
  33 // Identifies a CommandBufferStub. MediaGpuChannelManager is responsible
  34 // for minting |channel_token| values.
  35 struct CommandBufferId {
  36   mojo_base.mojom.UnguessableToken channel_token;
  37   int32 route_id;
  38 };
  39
  40 [Native]
  41 struct OverlayInfo;
  42
  43 // Interface for releasing remote VideoFrames. It is separated from VideoDecoder
  44 // so that VideoFrames can outlive their VideoDecoder.
  45 interface VideoFrameHandleReleaser {
  46   // Signals that the VideoFrame identified by |release_token| should be
  47   // released. |release_sync_token| indicates the last use of the VideoFrame
  48   // (in a GPU command buffer) by the client. If the VideoDecoder outputs frames
  49   // that have a callback for releasing mailboxes (i.e.,
  50   // VideoFrame::HasReleaseMailboxCB() returns true), the |release_sync_token|
  51   // is required but may be empty, and in that case, implementations should let
  52   // the about-to-be-released VideoFrame retain whatever SyncToken it has. For
  53   // other frames, it's assumed that the frame can be released immediately upon
  54   // calling ReleaseVideoFrame() and |release_sync_token| does not need to be
  55   // supplied (and should be ignored by implementations if supplied).
  56   ReleaseVideoFrame(mojo_base.mojom.UnguessableToken release_token,
  57                     gpu.mojom.SyncToken? release_sync_token);
  58 };
  59
  60 // A Mojo equivalent of media::VideoDecoder. In practice, this is used for
  61 // hardware decode offloading; in this case the client is a <video> tag running
  62 // in a renderer, and the implementation is running in the GPU process.
  63 interface VideoDecoder {
  64   // Returns a list of supported configs as well as the decoder ID for the decoder
  65   // which supports them. It is expected that Initialize() will fail for any config
  66   // that does not match an entry in this list.
  67   //
  68   // May be called before Construct().
  69   [Sync]
  70   GetSupportedConfigs() =>
  71       (array<SupportedVideoDecoderConfig> supported_configs,
  72        VideoDecoderType decoder_type);
  73
  74   // Initialize the decoder. This must be called before any method other than
  75   // GetSupportedConfigs().
  76   //
  77   // |client| provides asynchronous client methods to the VideoDecoder, such
  78   // as delivery of decoded VideoFrame outputs.
  79   //
  80   // When a VideoFrame is delivered to |client|, the VideoDecoder may continue
  81   // to retain a reference to the VideoFrame. In this case a |release_token| is
  82   // included. The client shall use |video_frame_handle_releaser| to signal
  83   // that the retained VideoFrame should be released (even after the
  84   // VideoDecoder is torn down). This enables ordinary VideoFrames in the client
  85   // process to depend on resources held by the service, without significantly
  86   // complicating VideoFrame serialization.
  87   //
  88   // |decoder_buffer_pipe| is used to transfer the encoded data for each
  89   // DecoderBuffer.
  90   //
  91   // |command_buffer_id|, when present, identifies a CommandBufferStub that
  92   // the VideoDecoder can use for GL operations. Implementations that require GL
  93   // will fail Initialize() if |command_buffer_id| is not provided.
  94   //
  95   // |implementation| selects the underlying VideoDecoder implementation.  Not
  96   // all implementations are supported.  Initialize() will fail if
  97   // |implementation| is not supported.
  98   //
  99   // TODO(sandersd): Rename to Initialize() if/when
 100   // media::VideoDecoder::Initialize() is renamed to Configure().
 101   Construct(
 102       pending_associated_remote<VideoDecoderClient> client,
 103       pending_remote<MediaLog> media_log,
 104       pending_receiver<VideoFrameHandleReleaser> video_frame_handle_releaser,
 105       handle<data_pipe_consumer> decoder_buffer_pipe,
 106       CommandBufferId? command_buffer_id,
 107       gfx.mojom.ColorSpace target_color_space);
 108
 109   // Configure (or reconfigure) the decoder. This must be called before decoding
 110   // any frames, and must not be called while there are pending Initialize(),
 111   // Decode(), or Reset() requests.
 112   //
 113   // If |low_delay| is true, the decoder must output frames as soon as possible;
 114   // in particular, it must not wait for another Decode() request, except as
 115   // required for frame reordering. Implementations must fail initialization if
 116   // they cannot satisfy this requirement.
 117   //
 118   // On completion, the callback also includes |needs_bitstream_conversion|,
 119   // indicating whether decode buffers need bitstream conversion, and
 120   // |max_decode_requests|, the maximum number of concurrent Decode() requests
 121   // the implementation supports.
 122   //
 123   // |cdm_id| must refer to a valid CDM if |config.is_encrypted()|.  It is not
 124   // used for unencrypted streams.
 125   Initialize(VideoDecoderConfig config, bool low_delay,
 126              mojo_base.mojom.UnguessableToken? cdm_id)
 127       => (DecoderStatus status,
 128           bool needs_bitstream_conversion,
 129           int32 max_decode_requests,
 130           VideoDecoderType decoder_type);
 131
 132   // Request decoding of exactly one frame or an EOS buffer. This must not be
 133   // called while there are pending Initialize(), Reset(), or Decode(EOS)
 134   // requests.
 135   //
 136   // Implementations must eventually execute the callback, even if Decode() is
 137   // not called again. It is not required that the decode status match the
 138   // actual result of decoding the buffer, only that decode errors are
 139   // eventually reported (such as at EOS).
 140   //
 141   // If |buffer| is an EOS buffer, implementations must execute all other
 142   // pending Decode() callbacks and output all pending frames before executing
 143   // the Decode(EOS) callback. (That is, they must flush.)
 144   Decode(DecoderBuffer buffer) => (DecoderStatus status);
 145
 146   // Reset the decoder. All ongoing Decode() requests must be completed or
 147   // aborted before executing the callback. This must not be called while there
 148   // is a pending Initialize() request.
 149   Reset() => ();
 150
 151   // Inform the decoder that new OverlayInfo is available.
 152   OnOverlayInfoChanged(OverlayInfo overlay_info);
 153 };
 154
 155 interface VideoDecoderClient {
 156   // Output a decoded frame. Frames are output in presentation order.
 157   //
 158   // When |can_read_without_stalling| is false, preroll should be disabled. This
 159   // is necessary if the decoder cannot guarantee that it can output another
 160   // frame, for example if output buffers are limited or configuration changes
 161   // require the return of all outstanding frames.
 162   //
 163   // If |release_token| is provided, the client shall call
 164   // VideoFrameHandleReleaser::Release() when it is finished using |frame|.
 165   OnVideoFrameDecoded(VideoFrame frame,
 166                       bool can_read_without_stalling,
 167                       mojo_base.mojom.UnguessableToken? release_token);
 168
 169   // Called when the remote decoder is waiting because of |reason|, e.g. waiting
 170   // for decryption key.
 171   OnWaiting(WaitingReason reason);
 172
 173   // Request to be notified when the current OverlayInfo changes. This results
 174   // in at least one call to OnOverlayInfoChanged() for the initial OverlayInfo.
 175   // |restart_for_transitions| sets whether the decoder should be restarted on
 176   // overlay transitions instead of receiving a call to OnOverlayInfoChanged().
 177   RequestOverlayInfo(bool restart_for_transitions);
 178 };