// Copyright 2019 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 blink.mojom;

import "media/mojo/mojom/media_player.mojom";
import "services/viz/public/mojom/compositing/surface_id.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";

// PictureInPictureSessionObserver is associated to a PictureInPictureSession at
// its creation. It receives all the events associated to the session lifetime.
interface PictureInPictureSessionObserver {
  // Called when the size of the window associated to the session has changed.
  OnWindowSizeChanged(gfx.mojom.Size size);

  // Called when the session is stopped, typically when the user closes the
  // Picture-in-Picture window or when another session has started. This will
  // not be called when `Stop()` is called on a PictureInPictureSession object.
  OnStopped();
};

// Representation of a Picture-in-Picture session. The caller receives this
// object back after a call to `StartSession()` on the main service. It can be
// used to interact with the session after its creation.
interface PictureInPictureSession {
  // Update the information used to create the session when it was created.
  // This call cannot happen after `Stop()`.
  Update(uint32 player_id,
      viz.mojom.SurfaceId? surface_id,
      gfx.mojom.Size natural_size,
      bool show_play_pause_button);

  // Request to stop the current session. It will close the Picture-in-Picture
  // window and make other calls related to the session no-ops.
  Stop() => ();
};

// PictureInPictureService is a Document-associated interface that lives in
// the browser process. It is responsible for implementing the browser-side
// support for https://wicg.github.io/picture-in-picture and manages all
// picture-in-picture interactions for Document. Picture-in-picture allows
// a Document to display a video in an always-on-top floating window with
// basic playback functionality (e.g. play and pause).
interface PictureInPictureService {
  // Notify the service that it should start a Picture-in-Picture session. If a
  // Picture-in-Picture session is already running, it will be closed.
  // player_id: WebMediaPlayer id used to control playback via the
  //            Picture-in-Picture window.
  // player_remote: MediaPlayer remote to communicate with the renderer side.
  // surface_id: SurfaceId to be shown in the Picture-in-Picture window.
  // natural_size: Size of the video frames.
  // show_play_pause_button: Whether a play/pause control should be offered in
  //                         the Picture-in-Picture window.
  // observer: Observer to be associated with the session.
  //
  // TODO: Now that we are passing |player_remote|, it should be possible to get
  // rid of |player_id| once the few remaining uses of it in the browser process
  // get migrated to not requiring a MediaPlayerId for identification purposes.
  StartSession(
      uint32 player_id,
      pending_associated_remote<media.mojom.MediaPlayer> player_remote,
      viz.mojom.SurfaceId? surface_id,
      gfx.mojom.Size natural_size,
      bool show_play_pause_button,
      pending_remote<PictureInPictureSessionObserver> observer)
          => (pending_remote<PictureInPictureSession>? session, gfx.mojom.Size size);
};