// 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 video_capture.mojom;

import "media_perception/mojom/video_capture_types.mojom";
import "media_perception/mojom/device.mojom";
import "media_perception/mojom/devices_changed_observer.mojom";
import "media_perception/mojom/producer.mojom";
import "media_perception/mojom/virtual_device.mojom";

enum DeviceAccessResultCode {
  NOT_INITIALIZED,
  SUCCESS,
  ERROR_DEVICE_NOT_FOUND
};

// Enables access to a set of video capture devices.
// Typical operation is to first call GetDeviceInfos() to obtain
// information about available devices. The |device_id| of the infos can
// subsequently be used to create an instance of
// video_capture.mojom.Device using CreateDevice().
// The factory guarantees that no two device infos it returns use the
// same |device_id|.
interface DeviceFactory {
  GetDeviceInfos()
      => (array<media.mojom.VideoCaptureDeviceInfo> device_infos);

  // Provides exclusive access to the device identified by |device_id|. The
  // access is valid until either the message pipe associated with
  // |device_receiver| is closed by the client, or a subsequent call to
  // CreateDevice() is made. When a subsequent call is made while the
  // |device_receiver| from a previous call has not yet been closed, the service
  // "revokes" that previous |device_receiver| (by closing the connection) and
  // the exclusive access goes to the new |device_receiver|.
  // Note: This design avoids the issue of it not being clear how soon after a
  // |device_receiver| has been (asynchronously) discarded a subsequent call to
  // CreateDevice() would succeed if it were to deny access while still in use.
  CreateDevice(string device_id, pending_receiver<Device> device_receiver)
      => (DeviceAccessResultCode result_code);

  // Creates a new virtual capture device, which will be exposed by the device
  // factory using the given |device_info|. The returned |virtual_device| is to
  // be used by the caller to subsequently push video frames. These frames will
  // appear to clients of the device as if they were produced by the device.
  // If |send_buffer_handles_to_producer_as_raw_file_descriptors| is set to
  // true, buffers requested via
  // |SharedMemoryVirtualDevice.RequestFrameBuffer()| will be shared with
  // |producer| as |VideoBufferHandle.shared_memory_via_raw_file_descriptor|,
  // and otherwise as |VideoBufferHandle.shared_buffer_handle|.
  // The virtual device is removed either when the caller releases
  // |virtual_device| or the given |producer| is closed.
  AddSharedMemoryVirtualDevice(
      media.mojom.VideoCaptureDeviceInfo device_info,
      pending_remote<Producer> producer,
      bool send_buffer_handles_to_producer_as_raw_file_descriptors,
      pending_receiver<SharedMemoryVirtualDevice> virtual_device_receiver);

  // Similar to AddSharedMemoryVirtualDevice() but for virtual devices that
  // are fed with textures (via MailboxHolders) allocated by the caller instead
  // of shared memory buffers provided by the service on demand.
  AddTextureVirtualDevice(
      media.mojom.VideoCaptureDeviceInfo device_info,
      pending_receiver<TextureVirtualDevice> virtual_device_receiver);

  // Add a virtual device with video frames backed by GpuMemoryBufferHandle.
  // The buffers are allocated and managed by the caller.
  AddGpuMemoryBufferVirtualDevice(
      media.mojom.VideoCaptureDeviceInfo device_info,
      pending_receiver<GpuMemoryBufferVirtualDevice> virtual_device_receiver);

  // Registered observers will get notified whenever a virtual device is added
  // or removed. Note: Changes to non-virtual devices are currently being
  // monitored outside the video capture service, and therefore the service
  // does not offer such monitoring.
  RegisterVirtualDevicesChangedObserver(
      pending_remote<DevicesChangedObserver> observer,
      bool raise_event_if_virtual_devices_already_present);
};