Mojo Video Capture service in media/capture

media/capture/interfaces/video_capture.mojom

Index: media/capture/interfaces/video_capture.mojom
diff --git a/media/capture/interfaces/video_capture.mojom b/media/capture/interfaces/video_capture.mojom
new file mode 100644
index 0000000000000000000000000000000000000000..d7503b4bda71f32ab598129f20fe902e13e1affe
--- /dev/null
+++ b/media/capture/interfaces/video_capture.mojom
@@ -0,0 +1,102 @@
+// 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.
+
+// This mojom defines the interface for enumerating Video Capture Devices and
+// selecting one for capturing. Such a VCD is manipulated via creation of a
+// Stream, which is then Start()ed to produce FrameInfos to a StreamCient. In
+// this sense, this API mimics a UserMediaClient.
+
+module media.mojom;
+
+import "media/mojo/interfaces/media_types.mojom";
+import "ui/mojo/geometry/geometry.mojom";
+
+// Copies of third_party/WebKit/public/platform/WebSourceInfo.h.
+enum SourceKind { None, Audio, Video };
+enum VideoFacingMode { None, User, Environment };
+struct WebSourceInfo {
+  string device_id;
+  string label;
+
+  SourceKind kind;  // Should always be blink::WebSourceInfo::SourceKindVideo
+
+  VideoFacingMode facing_mode;
+};
+
+struct StreamOptions {
+  string device_id;
+
+  // Replicate the used fields of VideoCaptureParams.
+  mojo.Size capture_size;
+  double frame_rate;
+  // TODO(mcasas): add and wire PowerLineFrequency and ResolutionChangePolicy.
+};
+
+// Information provided to a VideoStreamClient about an available video frame.
+struct FrameInfo {
+  // Shared memory handle to allocated storage for the frame. This handle may
+  // be mapped by the client for read-only access.
+  // TODO(mcasas): investigate if sharing this buffer per frame has any impact
+  // in performance. If so, reinstaurate a sharing-buffer-preamble.
+  handle<shared_buffer> storage_handle;
+  // Size in bytes of the allocated storage.
+  int32 storage_size;
+
+  // Pixel format of the frame data in storage.
+  media.interfaces.VideoFormat pixel_format;
+
+  // Size of the frame in pixels. This includes pixel data for the whole image;
+  // i.e. for YUV formats with subsampled chroma planes where the visible
+  // portion does not line up on a sample boundary, |coded_size| will be rounded
+  // up appropriately and pixel data will be provided for the odd pixels.
+  mojo.Size coded_size;
+
+  // Visible rectangle of pixels in the frame. This must be a subrect of
+  // |coded_rect|. May be odd with respect to the sample boundaries, e.g. for
+  // formats with subsampled chroma. This is used e.g. for letterboxing.
+  mojo.Rect visible_rect;
+
+  // A coded version of base::TimeTicks::Now() at the time the frame data was
+  // generated by its source. For the sake of consistency this must always be
+  // interpreted using base::TimeTicks::FromInternalValue or some equivalent.
+  int64 timestamp;
+};
+
+// The client interface for a Stream.
+interface StreamClient {
+  // Informs the client that new frame data is available. |info| provides
+  // details about this individual frame.
+  FrameAvailable(FrameInfo info) => ();
+
+  // Some Error has happened; the capture will in all likelihood be interrupted.
+  Error(string error);
+};
+
+// The Stream interface abstracts a distinct local source of video frame data

[perkj_chrome, 2016/03/03 13:12:41]

Is this right or wrong? it looks like this is only about video camera devices
which I think might simplify things. 

What is the idea with the other types you list here? How will that work in the
future? Separate mojo components? I think you should take the opportunity to
split that out from handling video cameras.

[mcasas, 2016/03/03 18:41:15]

I will limit the scope of the current CL to video capture
devices and write a TODO for the rest.

This also simplifies the current WebSourceInfo.
My personal opinion is that screen and tab should,
at this level, be treated as regular video capture
devices, and let the permissions and pickers be
dealt with elsewhere (by preference as mojo
services themselves). At this level we should get
just a message saying "hey, start capturing 
device X", or "please start capturing tab Z".

+// such as a camera device, desktop capture, web view capture.
+interface Stream {
+  // Starts sending frames to |client|. Must only be called once and must be the
+  // first call on the Stream.
+  Start(StreamClient client);
+
+  // Stops the capture, releasing all associated resources.
+  Stop();
+};
+
+// The primary top-level service interface exposed by the video_capture
+// component. This is used by a UserMediaClient implementation to get hold of a
+// Stream that can be Start()ed to produce video frames, so in a way, it is a
+// video-only flavour of WebUserMediaClient.
+// TODO(mcasas): Add a method to retrieve the capture capabilities of a given
+// |device_id|.
+interface VideoCaptureHandler {
+  // requestMediaDevices(const WebMediaDevicesRequest&)
+  RequestMediaDevices()
+      => (array<WebSourceInfo> devices);

[perkj_chrome, 2016/03/03 13:12:41]

I dont think you should copy blink structs. You will have to translate into
blink anyway so please use a chrome struct. To not make the change so huge, you
could use the same struct as we use today  StreamDeviceInfo? (not that it is any
good for video since it is polluted by audio stuff)

Can we call this EnumerateDevices?

[mcasas, 2016/03/03 18:41:15]

In the spirit of your comment before, let's call it
VideoCaptureDeviceInfo.
Done.

+
+  // requestUserMedia(const WebUserMediaRequest&)
+  RequestStream(StreamOptions options, string security_origin)

[perkj_chrome, 2016/03/03 13:12:41]

Can we call this OpenCamera or OpenVideoDevice? and StreamClient ->
VideoCameraClient or VideoDeviceClient  depending on if this interface will be
used for other video device types than cameras. ie, screen capture etc..
 

[mcasas, 2016/03/03 18:41:15]

RequestStream() ==> RequestVideoCaptureStream()
Stream ==> VideoCaptureStream
StreamClient ==> VideoCaptureStreamClient

+      => (Stream? stream);
+};
+