chromium/services/video_capture/public/mojom/video_source_provider.mojom

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

import "media/capture/mojom/video_capture_types.mojom";
import "services/video_capture/public/mojom/devices_changed_observer.mojom";
import "services/video_capture/public/mojom/producer.mojom";
import "services/video_capture/public/mojom/video_source.mojom";
import "services/video_capture/public/mojom/virtual_device.mojom";

// Provides access to a set of video sources. Some of the methods are specific
// to virtual devices that are used to simulate video capture devices, eg. for
// tests.
interface VideoSourceProvider {
  // Results of GetSourceInfos calls.
  enum GetSourceInfosResult {
    kSuccess,
    kErrorDroppedRequest
  };

  // Get a list of available video sources. source_infos is empty whenever
  // result is not kSuccess.
  GetSourceInfos() => (GetSourceInfosResult result,
                       array<media.mojom.VideoCaptureDeviceInfo> source_infos);

  // This essentially constrains things down to a particular source. This is
  // useful for subsequently passing the resulting |stream| to clients that
  // are supposed to get access to only a particular source.
  GetVideoSource(string source_id, pending_receiver<VideoSource> stream);

  // Creates a new virtual (non-physical) capture device, which will be exposed
  // 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,
      pending_receiver<SharedMemoryVirtualDevice> virtual_device_receiver);

  // Similar to AddSharedMemoryVirtualDevice() but for virtual (non-physical)
  // 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);

  // Registered observers will get notified whenever a virtual (non-physical)
  // device is added or removed.
  RegisterVirtualDevicesChangedObserver(
      pending_remote<DevicesChangedObserver> observer,
      bool raise_event_if_virtual_devices_already_present);

  // Registered observers will get notified whenever a device is added
  // or removed. Observers will be notified for both physical and virtual
  // devices.
  RegisterDevicesChangedObserver(
      pending_remote<DevicesChangedObserver> observer);

  // Closes the connection and allows clients to wait until the disconnect has
  // arrived at the service.
  Close() => ();
};