// 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 "media/capture/mojom/video_capture_buffer.mojom";
import "media/capture/mojom/video_capture_types.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";

// This file decribes the communication between a given Renderer Host interface
// implementation (VideoCaptureHost) and a remote VideoCaptureObserver.
// VideoCaptureHost offers a stateless part (GetDeviceSupportedFormats() and
// GetDeviceFormatsInUse()) that can be invoked at any time, and a stateful part
// sandwiched between Start() and Stop(). A Client's OnStateChanged() can be
// notified any time during the stateful part. The stateful part is composed of
// a preamble where a Renderer client sends a command to Start() the capture,
// registering itself as the associated remote VideoCaptureObserver. The Host
// will then create and pre- share a number of buffers:
//
//   Observer                                        VideoCaptureHost
//      | ---> StartCapture                                     |
//      |                        OnStateChanged(STARTED) <---   |
//      |                                 OnNewBuffer(1) <---   |
//      |                                 OnNewBuffer(2) <---   |
//      =                                                       =
// and capture will then refer to those preallocated buffers:
//      |                               OnBufferReady(1) <---   |
//      |                               OnBufferReady(2) <---   |
//      | ---> ReleaseBuffer(1)                                 |
//      |                               OnBufferReady(1) <---   |
//      | ---> ReleaseBuffer(2)                                 |
//      |                               OnBufferReady(2) <---   |
//      | ---> ReleaseBuffer(1)                                 |
//      |                         ...                           |
//      =                                                       =
// Buffers can be reallocated with a larger size, if e.g. resolution changes.
//      |                 (resolution change)                   |
//      |                           OnBufferDestroyed(1) <---   |
//      |                                 OnNewBuffer(3) <---   |
//      |                               OnBufferReady(3) <---   |
//      | ---> ReleaseBuffer(2)                                 |
//      |                           OnBufferDestroyed(2) <---   |
//      |                                 OnNewBuffer(5) <---   |
//      |                               OnBufferReady(5) <---   |
//      =                                                       =
// In the communication epilogue, the client Stop()s capture, receiving a last
// status update:
//      | ---> StopCapture                                      |
//      |                        OnStateChanged(STOPPED) <---   |

enum VideoCaptureState {
  STARTED,
  PAUSED,
  RESUMED,
  STOPPED,
  FAILED,
  ENDED,
};

// Interface for notifications from Browser/Host back to Renderer/Client. This
// interface is used between VideoCaptureHost.Start() and Stop().
interface VideoCaptureObserver {
  // Gets notified about a VideoCaptureState update.
  OnStateChanged(VideoCaptureState state);

  // Registers a |buffer_handle| at the Renderer/Client using the given
  // |buffer_id|. The Browser/Host may subsequently use |buffer_id| to share
  // video frames via calls to OnBufferReady().
  OnNewBuffer(int32 buffer_id, media.mojom.VideoBufferHandle buffer_handle);

  // |buffer| and |scaled_buffers| have capture data ready for consumption.
  OnBufferReady(ReadyBuffer buffer, array<ReadyBuffer> scaled_buffers);

  // The buffer handle previously registered for |buffer_id| via OnNewBuffer(),
  // is no longer going to be used by the Browser/Host.
  OnBufferDestroyed(int32 buffer_id);
};

interface VideoCaptureHost {
  // Start the |session_id| session with |params|. The video capture will be
  // identified as |device_id|, a new id picked by the renderer process.
  // |observer| will be used for notifications.
  Start(mojo_base.mojom.UnguessableToken device_id,
        mojo_base.mojom.UnguessableToken session_id,
        VideoCaptureParams params,
        pending_remote<VideoCaptureObserver> observer);

  // Closes the video capture specified by |device_id|.
  Stop(mojo_base.mojom.UnguessableToken device_id);

  // Pauses the video capture specified by |device_id|.
  Pause(mojo_base.mojom.UnguessableToken device_id);

  // Resume |device_id| video capture, in |session_id| and with |params|.
  Resume(mojo_base.mojom.UnguessableToken device_id,
         mojo_base.mojom.UnguessableToken session_id,
         VideoCaptureParams params);

  // Requests that the video capturer send a frame "soon" (e.g., to resolve
  // picture loss or quality issues).
  RequestRefreshFrame(mojo_base.mojom.UnguessableToken device_id);

  // Indicates that a renderer has finished using a previously shared buffer.
  ReleaseBuffer(mojo_base.mojom.UnguessableToken device_id, int32 buffer_id,
                VideoCaptureFeedback feedback);

  // Get the formats supported by a device referenced by |session_id|.
  GetDeviceSupportedFormats(mojo_base.mojom.UnguessableToken device_id,
                            mojo_base.mojom.UnguessableToken session_id)
    => (array<VideoCaptureFormat> formats_supported);

  // Get the format(s) in use by a device referenced by |session_id|.
  GetDeviceFormatsInUse(mojo_base.mojom.UnguessableToken device_id,
                        mojo_base.mojom.UnguessableToken session_id)
    => (array<VideoCaptureFormat> formats_in_use);

  // Notifies the host about a frame being dropped.
  OnFrameDropped(mojo_base.mojom.UnguessableToken device_id,
                 media.mojom.VideoCaptureFrameDropReason reason);

  // Sends a log message to the VideoCaptureHost.
  OnLog(mojo_base.mojom.UnguessableToken device_id, string message);
};