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

module media.mojom;

import "gpu/ipc/common/sync_token.mojom";
import "media/mojo/interfaces/media_log.mojom";
import "media/mojo/interfaces/media_types.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "ui/gfx/mojo/color_space.mojom";

// Identifies a CommandBufferStub. MediaGpuChannelManager is responsible
// for minting |channel_token| values.
struct CommandBufferId {
  mojo_base.mojom.UnguessableToken channel_token;
  int32 route_id;
};

interface VideoFrameHandleReleaser {
  // Signals that the VideoFrame identified by |release_token| should be
  // released. |release_sync_token| indicates the last use of the VideoFrame
  // (in a GPU command buffer) by the client.
  //
  // TODO(sandersd): Do we need release notification for non-texture
  // VideoFrames? If so, |release_sync_token| should be optional.
  ReleaseVideoFrame(mojo_base.mojom.UnguessableToken release_token,
                    gpu.mojom.SyncToken release_sync_token);
};

[Native]
struct OverlayInfo;

// A Mojo equivalent of media::VideoDecoder. In practice, this is used for
// hardware decode offloading; in this case the client is a <video> tag running
// in a renderer, and the implementation is running in the GPU process.
interface VideoDecoder {
  // Initialize the decoder. This must be called before any other method.
  //
  // |client| provides asynchronous client methods to the VideoDecoder, such
  // as delivery of decoded VideoFrame outputs.
  //
  // When a VideoFrame is delivered to |client|, the VideoDecoder may continue
  // to retain a reference to the VideoFrame. In this case a |release_token| is
  // included. The client shall use |video_frame_handle_releaser| to signal
  // that the retained VideoFrame should be released (even after the
  // VideoDecoder is torn down). This enables ordinary VideoFrames in the client
  // process to depend on resources held by the service, without significantly
  // complicating VideoFrame serialization.
  //
  // |decoder_buffer_pipe| is used to transfer the encoded data for each
  // DecoderBuffer.
  //
  // |command_buffer_id|, when present, identifies a CommandBufferStub that
  // the VideoDecoder can use for GL operations. Implementations that require GL
  // will fail Initialize() if |command_buffer_id| is not provided.
  //
  // TODO(sandersd): Rename to Initialize() if/when
  // media::VideoDecoder::Initialize() is renamed to Configure().
  Construct(associated VideoDecoderClient client,
            associated MediaLog media_log,
            VideoFrameHandleReleaser& video_frame_handle_releaser,
            handle<data_pipe_consumer> decoder_buffer_pipe,
            CommandBufferId? command_buffer_id,
            gfx.mojom.ColorSpace target_color_space);

  // Configure (or reconfigure) the decoder. This must be called before decoding
  // any frames, and must not be called while there are pending Initialize(),
  // Decode(), or Reset() requests.
  //
  // If |low_delay| is true, the decoder must output frames as soon as possible;
  // in particular, it must not wait for another Decode() request, except as
  // required for frame reordering. Implementations must fail initialization if
  // they cannot satisfy this requirement.
  //
  // On completion, the callback also includes |needs_bitstream_conversion|,
  // indicating whether decode buffers need bitstream conversion, and
  // |max_decode_requests|, the maximum number of concurrent Decode() requests
  // the implementation supports.
  //
  // |cdm_id| must refer to a valid CDM if |config.is_encrypted()|.  It is not
  // used for unencrypted streams.
  Initialize(VideoDecoderConfig config, bool low_delay, int32 cdm_id) =>
      (bool success, bool needs_bitstream_conversion,
       int32 max_decode_requests);

  // Request decoding of exactly one frame or an EOS buffer. This must not be
  // called while there are pending Initialize(), Reset(), or Decode(EOS)
  // requests.
  //
  // Implementations must eventually execute the callback, even if Decode() is
  // not called again. It is not required that the decode status match the
  // actual result of decoding the buffer, only that decode errors are
  // eventually reported (such as at EOS).
  //
  // If |buffer| is an EOS buffer, implementations must execute all other
  // pending Decode() callbacks and output all pending frames before executing
  // the Decode(EOS) callback. (That is, they must flush.)
  Decode(DecoderBuffer buffer) => (DecodeStatus status);

  // Reset the decoder. All ongoing Decode() requests must be completed or
  // aborted before executing the callback. This must not be called while there
  // is a pending Initialize() request.
  Reset() => ();

  // Inform the decoder that new OverlayInfo is available.
  OnOverlayInfoChanged(OverlayInfo overlay_info);
};

interface VideoDecoderClient {
  // Output a decoded frame. Frames are output in presentation order.
  //
  // When |can_read_without_stalling| is false, preroll should be disabled. This
  // is necessary if the decoder cannot guarantee that it can output another
  // frame, for example if output buffers are limited or configuration changes
  // require the return of all outstanding frames.
  //
  // If |release_token| is provided, the client shall call
  // VideoFrameHandleReleaser::Release() when it is finished using |frame|.
  OnVideoFrameDecoded(VideoFrame frame,
                      bool can_read_without_stalling,
                      mojo_base.mojom.UnguessableToken? release_token);

  // Request to be notified when the current OverlayInfo changes. This results
  // in at least one call to OnOverlayInfoChanged() for the initial OverlayInfo.
  // |restart_for_transitions| sets whether the decoder should be restarted on
  // overlay transitions instead of receiving a call to OnOverlayInfoChanged().
  RequestOverlayInfo(bool restart_for_transitions);
};