VideoCapture: more migration IPC-->mojo, part 6

content/common/video_capture.mojom

 // 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 content.mojom;
 
 import "gpu/ipc/common/sync_token.mojom";
 import "media/mojo/interfaces/media_types.mojom";
 import "mojo/common/common_custom_types.mojom";
 import "services/video_capture/public/interfaces/video_capture_device_proxy.mojom";
 import "services/video_capture/public/interfaces/video_capture_format.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) ----   |
+//      | <------- OnBufferCreated(1) --------   |
+//      | <------- OnBufferCreated(2) --------   |
+//
+// and capture will then refer to those preallocated buffers:
+//      |                                        |
+//      | <-------- OnBufferReady(1) ---------   |
+//      | <-------- OnBufferReady(2) ---------   |
+//      | -------- ReleaseBuffer(1) --------->   |
+//      | <-------- OnBufferReady(1) ---------   |
+//      | -------- ReleaseBuffer(2) --------->   |
+//      | <-------- OnBufferReady(2) ---------   |
+//      | -------- ReleaseBuffer(1) --------->   |

[ncarter (slow), 2016/10/19 18:58:21]

This might be easier to look at with more whitespace for visual rhythm, and with
the numbers from each side of the communication are vertically aligned, as if in
a table. Maybe like:

 //      |                       <-- OnBufferReady(1) |
 //      |                       <-- OnBufferReady(2) |
 //      | --> ReleaseBuffer(1)                       |
 //      |                       <-- OnBufferReady(1) |
 //      | --> ReleaseBuffer(2)                       |

[mcasas, 2016/10/19 19:29:51]

Good suggestion. Done.

+//      |             ...                        |
+//      =                                        =
+//      |             ... (resolution change)    |
+//      | <------ OnBufferDestroyed(1) -------   |  Buffers can be re-allocated
+//      | <------- OnBufferCreated(3) --------   |  with a larger size, as
+//      | <-------- OnBufferReady(3) ---------   |  needed.
+//      | -------- ReleaseBuffer(1) --------->   |
+//      | <------ OnBufferDestroyed(2) -------   |
+//      | <------- OnBufferCreated(5) --------   |
+//      | <-------- OnBufferReady(5) ---------   |
+//
+// In the communication epilogue, the client Stop()s capture, receiving a last
+// status update:
+//
+//      |  --------- StopCapture --------->      |
+//      | <------ OnStateChanged(STOPPED) ----   |
+
 struct VideoCaptureParams {
   video_capture.mojom.VideoCaptureFormat requested_format;
   video_capture.mojom.ResolutionChangePolicy resolution_change_policy;
   video_capture.mojom.PowerLineFrequency power_line_frequency;
 };
 
 struct VideoFrameInfo{
   mojo.common.mojom.TimeDelta timestamp;
   mojo.common.mojom.DictionaryValue metadata;
   media.mojom.VideoPixelFormat pixel_format;
@@ skipping 10 matching lines @@
   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);
 
+  // A new buffer identified by |buffer_id| has been created for video capture.
+  OnBufferCreated(int32 buffer_id, handle<shared_buffer> handle_fd);
+
   // |buffer_id| has video capture data with |info| containing the associated
   // VideoFrame constituent parts.
   OnBufferReady(int32 buffer_id, VideoFrameInfo info);
 
   // |buffer_id| has been released by VideoCaptureHost and must not be used.
   OnBufferDestroyed(int32 buffer_id);
-
-  // TODO(mcasas): Migrate the rest of the messages, https://crbug.com/651897.
 };
 
 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|.
@@ skipping 15 matching lines @@
                 double consumer_resource_utilization);
 
   // Get the formats supported by a device referenced by |session_id|.
   GetDeviceSupportedFormats(int32 device_id, int32 session_id)
     => (array<video_capture.mojom.VideoCaptureFormat> formats_supported);
 
   // Get the format(s) in use by a device referenced by |session_id|.
   GetDeviceFormatsInUse(int32 device_id, int32 session_id)
     => (array<video_capture.mojom.VideoCaptureFormat> formats_in_use);
 };