blob: e074393c38df225cbbc706f53720aebb23ade743 [file] [log] [blame]
// 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 media.mojom;
import "media/capture/mojom/video_capture_types.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";
// This file decribes the communication between a given Renderer Host interface
// implementation (VideoCaptureHost) and a remote VideoCaptureObserver.
// VideoCaptureHost offers a stateless part (GetDeviceSupportedFormats() and
// GetDeviceFormatsInUse()) that can be invoked at any time, and a stateful part
// sandwiched between Start() and Stop(). A Client's OnStateChanged() can be
// notified any time during the stateful part. The stateful part is composed of
// a preamble where a Renderer client sends a command to Start() the capture,
// registering itself as the associated remote VideoCaptureObserver. The Host
// will then create and pre- share a number of buffers:
//
// Observer VideoCaptureHost
// | ---> StartCapture |
// | OnStateChanged(STARTED) <--- |
// | OnNewBuffer(1) <--- |
// | OnNewBuffer(2) <--- |
// = =
// and capture will then refer to those preallocated buffers:
// | OnBufferReady(1) <--- |
// | OnBufferReady(2) <--- |
// | ---> ReleaseBuffer(1) |
// | OnBufferReady(1) <--- |
// | ---> ReleaseBuffer(2) |
// | OnBufferReady(2) <--- |
// | ---> ReleaseBuffer(1) |
// | ... |
// = =
// Buffers can be reallocated with a larger size, if e.g. resolution changes.
// | (resolution change) |
// | OnBufferDestroyed(1) <--- |
// | OnNewBuffer(3) <--- |
// | OnBufferReady(3) <--- |
// | ---> ReleaseBuffer(2) |
// | OnBufferDestroyed(2) <--- |
// | OnNewBuffer(5) <--- |
// | OnBufferReady(5) <--- |
// = =
// In the communication epilogue, the client Stop()s capture, receiving a last
// status update:
// | ---> StopCapture |
// | OnStateChanged(STOPPED) <--- |
enum VideoCaptureState {
STARTED,
PAUSED,
RESUMED,
STOPPED,
FAILED,
ENDED,
};
// Interface for notifications from Browser/Host back to Renderer/Client. This
// interface is used between VideoCaptureHost.Start() and Stop().
interface VideoCaptureObserver {
// Gets notified about a VideoCaptureState update.
OnStateChanged(VideoCaptureState state);
// Registers a |buffer_handle| at the Renderer/Client using the given
// |buffer_id|. The Browser/Host may subsequently use |buffer_id| to share
// video frames via calls to OnBufferReady().
OnNewBuffer(int32 buffer_id, media.mojom.VideoBufferHandle buffer_handle);
// |buffer_id| has video capture data with |info| containing the associated
// VideoFrame constituent parts.
OnBufferReady(int32 buffer_id, VideoFrameInfo info);
// The buffer handle previously registered for |buffer_id| via OnNewBuffer(),
// is no longer going to be used by the Browser/Host.
OnBufferDestroyed(int32 buffer_id);
};
interface VideoCaptureHost {
// Start the |session_id| session with |params|. The video capture will be
// identified as |device_id|, a new id picked by the renderer process.
// |observer| will be used for notifications.
Start(int32 device_id, int32 session_id, VideoCaptureParams params,
VideoCaptureObserver observer);
// Closes the video capture specified by |device_id|.
Stop(int32 device_id);
// Pauses the video capture specified by |device_id|.
Pause(int32 device_id);
// Resume |device_id| video capture, in |session_id| and with |params|.
Resume(int32 device_id, int32 session_id, VideoCaptureParams params);
// Requests that the video capturer send a frame "soon" (e.g., to resolve
// picture loss or quality issues).
RequestRefreshFrame(int32 device_id);
// Indicates that a renderer has finished using a previously shared buffer.
ReleaseBuffer(int32 device_id, int32 buffer_id,
double consumer_resource_utilization);
// Get the formats supported by a device referenced by |session_id|.
GetDeviceSupportedFormats(int32 device_id, int32 session_id)
=> (array<VideoCaptureFormat> formats_supported);
// Get the format(s) in use by a device referenced by |session_id|.
GetDeviceFormatsInUse(int32 device_id, int32 session_id)
=> (array<VideoCaptureFormat> formats_in_use);
// Notifies the host about a frame being dropped.
OnFrameDropped(int32 device_id,
media.mojom.VideoCaptureFrameDropReason reason);
// Sends a log message to the VideoCaptureHost.
OnLog(int32 device_id, string message);
};