services/video_capture/public/mojom/video_source.mojom

// Copyright 2019 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/capture/mojom/image_capture.mojom";
import "media/capture/mojom/video_capture_types.mojom";
import "services/video_capture/public/mojom/receiver.mojom";

enum CreatePushSubscriptionResultCode {
  kCreatedWithRequestedSettings,
  kCreatedWithDifferentSettings,
  kFailed,
};

// In a PushVideoStreamSubscription, the provider pushes frames to the
// subscriber at a rate determined by the provider. Using this interface, the
// subscriber can make adjustments/modification to the subscription.
interface PushVideoStreamSubscription {
  // For newly created subscriptions, the provider waits for this activation
  // call before starting to push frames to |subscriber|. This allows the
  // creator of the subscription to close or discard it before any frames are
  // pushed to |subscriber| in case the obtained settings are unacceptable.
  Activate();

  // When suspended, the subscriber will no longer receive any calls to
  // OnFrameReadyInBuffer() and OnFrameDropped(), but will still receive any
  // other calls, e.g. OnNewBuffer() and OnBufferRetired().
  // Callers may wait for the empty callback event to get notified when it is
  // guaranteed that no more frames will be pushed.
  Suspend() => ();

  Resume();

  GetPhotoState()
      => (media.mojom.PhotoState? capabilities);
  // Sets controls such as focus/zoom/white balance etc.
  // Note, depending on the implementation, some of these settings may or may
  // not affect the live video stream while others may only take effect during
  // TakePhoto().
  // Note, these settings affect the device globally, i.e. they may affect
  // other subscribers if there are any.
  SetPhotoOptions(media.mojom.PhotoSettings settings)
      => (bool success);
  TakePhoto()
      => (media.mojom.Blob? blob);

  // Closes the subscription. The callback indicates when the closing is
  // complete. After closing is complete, the subscriber will no longer receive
  // any calls from the subscription.
  // Note, that creating a new subscription for the same video source before
  // waiting for closing of existing subscriptions to complete may lead to the
  // source still being considered in-use. When that happens, any new settings
  // requested for the new subscription will be ignored unless
  // |force_reopen_with_new_settings| is set to true.
  Close() => ();
};

// Provides shared access to a specific video source to potentially multiple
// subscribers.
interface VideoSource {
  // Creates a subscription to the video source that will push video frames to
  // |subscriber| once it is activated. If this is the first subscriber, or if
  // |force_reopen_with_new_settings| is set to true, the service will attempt
  // to open the source such that it delivers frame in a format close to
  // |requested_settings|, but it does not give any guarantee that
  // |requested_settings| will actually be matched. The actual format of each
  // frame being delivered to |subscriber| is specified in the parameter
  // |frame_info| for each invocation of method OnFrameReadyInBuffer(). The
  // service does not guarantee that this format stays the same throughout the
  // lifetime of a subscription.
  // If the VideoSource is already in use by other subscribers and
  // |force_reopen_with_new_settings| is set to false, the underlying video
  // source will not be reopened, and |settings_source_was_opened_with| will
  // indicate what settings were requested by the subscriber that last caused
  // the underlying source to be opened or reopened.
  // If |force_reopen_with_new_settings| is set to true and |requested_settings|
  // is different from the settings that have been used to open the source, the
  // source will be reopened trying to match |requested_settings|. This will
  // potentially briefly interrupt the video stream received by other
  // subscribers.
  CreatePushSubscription(Receiver subscriber,
                         media.mojom.VideoCaptureParams requested_settings,
                         bool force_reopen_with_new_settings,
                         PushVideoStreamSubscription& subscription)
      => (CreatePushSubscriptionResultCode result_code,
          media.mojom.VideoCaptureParams settings_source_was_opened_with);
};