Define frame subscription interface and implementation on Mac

content/port/browser/render_widget_host_view_frame_subscriber.h

+// Copyright (c) 2012 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.
+
+#ifndef CONTENT_PORT_BROWSER_RENDER_WIDGET_HOST_VIEW_FRAME_SUBSCRIBER_H_
+#define CONTENT_PORT_BROWSER_RENDER_WIDGET_HOST_VIEW_FRAME_SUBSCRIBER_H_
+
+#include "base/time.h"
+
+namespace gfx {
+class Rect;
+class Size;
+}  // namespace gfx
+
+namespace media {
+class VideoFrame;
+}  // namespace media
+
+namespace content {
+
+// Defines an interface for listening to events of frame presentation
+// and to instruct the platform layer (i.e. RenderWidgetHostViewPort) to
+// copy a frame.
+//
+// Further processing is possible (e.g. scale and clip) through this
+// interface. See ShouldCaptureFrame() for details.
+class RenderWidgetHostViewFrameSubscriber {
+ public:
+  virtual ~RenderWidgetHostViewFrameSubscriber() {}
+
+  // Called when a new frame is going to be presented. Implementation can
+  // decide whether the current frame should be captured or not. Frame size
+  // is given such that implementor can choose to apply scaling and clipping
+  // to the frame captured. |src_size| is the size of the frame going to
+  // be presented, |src_subrect| will be set to choose clipping rectangle
+  // and |dst_subrect| will be set to choose destination rectangle.
+  //
+  // Return true if the current frame should be captured. If so, |storage|
+  // should will be set to hold an appropriately sized and allocated buffer
+  // into which to copy the frame.
+  //
+  // Destination format is determined by |storage|, currently only
+  // media::VideoFrame::RGB32 and media::VideoFrame::YV12 are supported.

[ncarter (slow), 2013/02/16 02:45:22]

Why support RGB32 destinations? Who is that for?

[Alpha Left Google, 2013/02/20 21:34:50]

Dropped RGB32, we'll do YV12 in SW as fallback for mac initially.

+  // Platform layer will perform color space conversion if needed.
+  //
+  // Return false if the current frame should not be captured.
+  virtual bool ShouldCaptureFrame(
+      const gfx::Size& src_size,
+      gfx::Rect* src_subrect,
+      gfx::Rect* dst_subrect,
+      scoped_refptr<media::VideoFrame>* storage) = 0;
+
+  // Called when a frame is captured. |frame| contains the content of
+  // a frame presented at time |timestamp| and ownership is transferred to
+  // the subscriber.
+  virtual void FrameCaptured(
+      const scoped_refptr<media::VideoFrame>& frame,
+      base::Time timestamp) = 0;

[ncarter (slow), 2013/02/16 02:45:22]

What happens in the event of errors? Seems like the subscriber needs to be
notified that the capture operation is no longer in flight.

I'd caution you against relying on the "no longer needed callback" that
VideoFrame has, because the subscriber is going to be an intermediary between
the allocator of the frames (VideoCaptureController leases shared memory to us)
and the filler of the frames (the RWHVP). So by letting the refcount fall to
zero, the RWHVP will be able tell the VideoCaptureController that a frame is
recycled, but the Subscriber might think it's still outstanding.

[Alpha Left Google, 2013/02/20 21:34:50]

I've changed this interface to accept a boolean. This means the frame contains
invalid content. This allows the platform layer to return a frame when it is not
able to capture a frame or the presenter is shutting down.

+};
+
+}  // namespace content
+
+#endif  // CONTENT_PORT_BROWSER_RENDER_WIDGET_HOST_VIEW_FRAME_SUBSCRIBER_H_