// Copyright 2015 The Chromium Authors
// 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/mojo/mojom/audio_decoder.mojom";
import "media/mojo/mojom/audio_encoder.mojom";
import "media/mojo/mojom/decryptor.mojom";
import "media/mojo/mojom/content_decryption_module.mojom";
import "media/mojo/mojom/media_log.mojom";
import "media/mojo/mojom/media_types.mojom";
import "media/mojo/mojom/renderer.mojom";
import "media/mojo/mojom/renderer_extensions.mojom";
import "media/mojo/mojom/video_decoder.mojom";
import "mojo/public/mojom/base/token.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";

// A disconnection of this interface can be interpreted as the
// VideoDecoder implementation created by
// InterfaceFactory.CreateVideoDecoderWithTracker() having been destroyed
// (or never bound in the first place).
//
// This interface is intended to be implemented by the browser process and used
// by the video decoder processes.
[EnableIf=allow_oop_video_decoder]
interface VideoDecoderTracker {};

// A factory for creating media mojo interfaces. Renderers can only access
// ContentDecryptionModules created with the same factory.
interface InterfaceFactory {
  CreateAudioDecoder(pending_receiver<AudioDecoder> audio_decoder);

  // Creates a VideoDecoder (|video_decoder|). If |dst_video_decoder| is
  // provided and supported by the implementation, VideoDecoder calls on
  // |video_decoder| should be forwarded to |dst_video_decoder|. This is
  // intended to be used for out-of-process video decoding in which
  // the GPU process acts a proxy between a renderer and a video decoder process
  // so that it can create a gpu::Mailbox for each decoded frame. As such, only
  // the GPU process should be provided with a valid |dst_video_decoder|.
  CreateVideoDecoder(
      pending_receiver<VideoDecoder> video_decoder,
      pending_remote<media.mojom.VideoDecoder>? dst_video_decoder);

  // Creates a VideoDecoder and should be called by the browser process.
  // If |tracker| is provided, the caller can handle its disconnection in order
  // to know when the VideoDecoder implementation is destroyed. Note that
  // |tracker| may get disconnected without ever creating a VideoDecoder
  // implementation instance, e.g., if an error occurs that prevents |receiver|
  // from being bound to an implementation. This method is intended to be used
  // only for OOP-VD.
  [EnableIf=allow_oop_video_decoder]
  CreateVideoDecoderWithTracker(
      pending_receiver<VideoDecoder> receiver,
      pending_remote<VideoDecoderTracker>? tracker);

  // Creates an AudioEncoder bound to a given receiver.
  CreateAudioEncoder(pending_receiver<AudioEncoder> audio_encoder);

  // Creates a regular media::Renderer (RendererImplFactory).
  // TODO(guohuideng): remove |audio_device_id|, it's not used.
  // TODO(crbug.com/40242503): Rename this call.
  CreateDefaultRenderer(string audio_device_id,
                        pending_receiver<Renderer> renderer);

  [EnableIf=enable_cast_renderer]
  // Creates a CastRenderer (CastRendererClientFactory).
  // This is used on Chromecast only. The |overlay_plane_id| is generated by
  // VideoOverlayFactory owned by MojoRenderer, therefore identifies the
  // MojoRenderer. With |overlay_plane_id|, The service can keep track of
  // which hosted CastRenderer is associated with which client.
  // This is necessary because MediaService will need to look up CastRenderer
  // by the |overlay_plane_id| to set video geometry on.
  CreateCastRenderer(mojo_base.mojom.UnguessableToken overlay_plane_id,
                     pending_receiver<Renderer> renderer);

  [EnableIf=is_win]
  // Creates a MediaFoundationRenderer (MediaFoundationRendererClientFactory).
  // - |renderer_extension| is bound in MediaFoundationRenderer, and receives
  //   calls from MediaFoundationRendererClient.
  CreateMediaFoundationRenderer(
      pending_remote<MediaLog> media_log,
      pending_receiver<Renderer> renderer,
      pending_receiver<MediaFoundationRendererExtension> renderer_extension);

  [EnableIf=is_android]
  // Creates a FlingingRenderer (FlingingRendererClientFactory).
  // The |presentation_id| is used to find an already set-up RemotePlayback
  // session (see blink::RemotePlayback).
  CreateFlingingRenderer(
      string presentation_id,
      pending_remote<FlingingRendererClientExtension> client_extension,
      pending_receiver<Renderer> renderer);

  // Creates a CDM based on the `cdm_config` provided. The `key_system` in the
  // `cdm_config` is a generic term for a decryption mechanism and/or content
  // protection provider. It should be a reverse domain name,
  // e.g. "com.example.somesystem". However, this call may be initiated by an
  // untrusted process (e.g. renderer), so the implementation must fully
  // validate `key_system` before creating the CDM. `cdm_config` specifies other
  // properties of the CDM which may influence creation. Upon failure, the
  // returned `cdm` and `cdm_context` will be null, and `status` will
  // specify the error reason. Upon success, `cdm` and `cdm_context` will be
  // valid, and `status` will be CreateCdmStatus::kSuccess.
  CreateCdm(CdmConfig cdm_config) =>
            (pending_remote<ContentDecryptionModule>? cdm,
             CdmContext? cdm_context,
             CreateCdmStatus status);
};