// Copyright 2019 The Chromium Authors
// 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 "media/mojo/mojom/media_types.mojom";
import "services/media_session/public/mojom/media_session.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,
      pending_associated_remote<media.mojom.MediaPlayer> player_remote,
      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() => ();

  // Notifies the session that the associated player's position has been
  // updated.
  UpdateMediaPosition(media_session.mojom.MediaPosition media_position);
};

// 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).
// The window provides playback control by translating user actions into
// media.mojom.MediaPlayer messages. The MediaPlayer remote can be reset by the
// renderer even while the Picute-in-Picture session is active, indicating that
// the media player is gone. A new MediaPlayer remote can be provided later by
// an Update() message to the PictureInPictureSession object.
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.
  //
  // Consecutive invocations of StartSession will preempt and cancel any pending
  // immersive confirmation flow from a previous call.
  //
  // 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.
  // source_bounds: Rectangle in the main frame's coordinate space where the
  //                video is displayed in physical pixels. This does not need
  //                to be exact; it will only be used to help the visual
  //                transition into picture in picture.
  // request_immersive: Whether to start an immersive Picture-in-Picture
  //                    session (prompting the user for options if needed).
  // spatial_format: Spatial format of the video to be played in the
  //                 immersive Picture-in-Picture session.
  //
  // The callback returns:
  // session: The session interface pointer. This will be null if the session
  //          creation fails, or if the user denies or cancels the immersive
  //          playback confirmation prompt.
  // size: The size of the picture-in-picture window.
  //
  // 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,
      gfx.mojom.Rect source_bounds,
      bool request_immersive,
      media.mojom.VideoSpatialFormat spatial_format)
          => (pending_remote<PictureInPictureSession>? session,
              gfx.mojom.Size size);
};