media_perception/mojom/device.mojom

// Copyright 2016 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_perception/mojom/video_capture_types.mojom";
import "media_perception/mojom/image_capture.mojom";
import "media_perception/mojom/video_frame_handler.mojom";

// Represents access to a video capture device available on the machine. The
// device is stopped automatically when the message pipe corresponding to either
// the Device or the given |handler| is closed. Note that as a response to
// stopping the device, the service may still need to send out events such as
// VideoFrameHandler.OnBufferRetired() to |handler|. The service will send a
// final event VideoFrameHandler.OnStopped() to indicate that stopping has
// completed and no further events are going to be sent to |handler|.
interface Device {
  Start(media.mojom.VideoCaptureParams requested_settings,
        pending_remote<VideoFrameHandler> handler);
  MaybeSuspend();
  Resume();
  GetPhotoState()
      => (media.mojom.PhotoState? capabilities);
  SetPhotoOptions(media.mojom.PhotoSettings settings)
      => (bool success);
  TakePhoto()
      => (media.mojom.Blob? blob);
  // |feedback| contains consumer feedback like resource utilization,
  // maximum requested frame-rate and resolution.
  ProcessFeedback(media.mojom.VideoCaptureFeedback feedback);

  // In cases where the video capturer self-pauses (e.g., a screen capturer
  // where the screen's content has not changed in a while), consumers may call
  // this to request a "refresh frame" be delivered to the Client.  This is used
  // in a number of circumstances, such as:
  //
  //   1. An additional consumer of video frames is starting up and requires a
  //      first frame (as opposed to not receiving a frame for an indeterminate
  //      amount of time).
  //   2. A few repeats of the same frame would allow a lossy video encoder to
  //      improve the video quality of unchanging content.
  //
  // The default implementation is a no-op. VideoCaptureDevice implementations
  // are not required to honor this request, especially if they do not
  // self-pause and/or if honoring the request would cause them to exceed their
  // configured maximum frame rate. Any VideoCaptureDevice that does self-pause,
  // however, should provide an implementation of this method that makes
  // reasonable attempts to honor these requests.
  RequestRefreshFrame();
};