Add content::SurfaceCapturer

content/common/gpu/surface_capturer.h

Index: content/common/gpu/surface_capturer.h
diff --git a/content/common/gpu/surface_capturer.h b/content/common/gpu/surface_capturer.h
new file mode 100644
index 0000000000000000000000000000000000000000..9b157cd6ae608067abf1d7221306b14dd3e89292
--- /dev/null
+++ b/content/common/gpu/surface_capturer.h
@@ -0,0 +1,97 @@
+// Copyright (c) 2013 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_COMMON_GPU_SURFACE_CAPTURER_H_
+#define CONTENT_COMMON_GPU_SURFACE_CAPTURER_H_
+
+#include "content/common/content_export.h"
+#include "media/base/video_frame.h"
+
+namespace gfx {
+
+class Size;
+class Rect;
+
+};  // namespace ui

[Pawel Osciak, 2013/08/24 01:29:31]

s/;//

[sheu, 2013/08/26 21:30:52]

Done.

+
+namespace content {
+
+// Surface capturer interface.  This interface is implemented by classes
+// that perform image capturing from the backbuffer.
+class CONTENT_EXPORT SurfaceCapturer {
+ public:
+  enum Error {
+    // Invalid argument was passed to an API method.
+    kInvalidArgumentError,
+    // A failure occurred at the GPU process or one of its dependencies.
+    // Examples of such failures include GPU hardware failures, GPU driver
+    // failures, GPU library failures, GPU process programming errors, and so
+    // on.
+    kPlatformFailureError,
+  };
+
+  class CONTENT_EXPORT Client {
+   public:
+    // Callback to notify client of parameters of the backbuffer capture.  Every
+    // time the Client receives this callback, subsequent media::VideoFrames
+    // passed to Capture() should mind the new parameters.

[Pawel Osciak, 2013/08/24 01:29:31]

s/Capture()/CopyCaptureToVideoFrame()/ ?
But personally I like Capture() much better. I don't see why bother saying
"Copy". And we pass VF, so it should be obvious too. We just want the capturer
to Capture() into our VF...

[sheu, 2013/08/26 21:30:52]

I wanted to make the two-stage nature of the capture clear.  TryCapture only
captures into a temporary buffer, and CopyCaptureToVideoFrame copies this
temporary into the output video frame.

+    // Parameters:
+    //  |buffer_size| is the required logical size (in pixels) of the buffer
+    //  to capture to (corresponds to |frame->coded_size()| from in Capture().

[Pawel Osciak, 2013/08/24 01:29:31]

s/from//

[sheu, 2013/08/26 21:30:52]

Done.

+    //  |visible_rect| is the visible subrect of the actual screen capture
+    //  contents in the buffer to capture to (corresponds to
+    //  |frame->visible_rect()| in Capture().
+    virtual void NotifyCaptureParameters(const gfx::Size& buffer_size,
+                                         const gfx::Rect& visible_rect) = 0;
+
+    // Callback to notify client that CopyCaptureToVideoFrame() has been
+    // completed for |frame|.  After this call, the capturer will drop all its
+    // outstanding references to |frame|.
+    // Parameters:
+    //  |frame| is the completed copied captured frame.
+    virtual void NotifyCopyCaptureDone(

[Pawel Osciak, 2013/08/24 01:29:31]

NotifyFrameReady?

[sheu, 2013/08/26 21:30:52]

I'd like the notification name to reflect the API entry point it callbacks for.

+        const scoped_refptr<media::VideoFrame>& frame) = 0;
+
+    // Error notification callback.
+    // Parameters:
+    //  |error| is the error to report.
+    virtual void NotifyError(Error error) = 0;
+
+   protected:
+    // Clients are not owned by Capturer instances and should not be deleted
+    // through these pointers.
+    virtual ~Client() {}
+  };
+
+  // Initialize the capturer to a specific configuration.
+  // Parameters:
+  //  |format| is the format to capture to (corresponds to |frame->format()| in
+  //  Capture()).
+  virtual void Initialize(media::VideoFrame::Format format) = 0;

[Pawel Osciak, 2013/08/24 01:29:31]

I'm assuming NotifyError() if the format is unsupported? Doco.
How do we know Initialize succeeded (i.e. that we can now capture stuff)? We get
NotifyCaptureParameters? Doco?

[sheu, 2013/08/26 21:30:52]

Done.

+
+  // Attempt to capture a frame.  This call is advisory to note to the
+  // SurfaceCapturer that capture should be attempted at this time; success is
+  // not guaranteed.  The most recent captured frame is cached internally, and
+  // its contents returned every time CopyCaptureToVideoFrame() is called.
+  virtual void TryCapture() = 0;

[Pawel Osciak, 2013/08/24 01:29:31]

You mean this starts capturing frames continuously? Doco.
What happens on failure? NotifyError?

I'm wondering, should we try to specify fps? Most of the time we would not be
interested in capturing at 60fps, sometimes not even 30?

How do we stop? Destroy?

[sheu, 2013/08/26 21:30:52]

This callback makes one frame capture attempt.  Updated the comment.

Basically, this call should be made every time the surface contents have changed
and are about to be swapped, to cache its contents.  Every time you want the
result of the capture, the CopyCaptureToVideoFrame() entry point is used.

+
+  // Copy the most recent captured contents to |frame|.
+  // Parameters:
+  //  |frame| is the media::VideoFrame to fill with captured contents.
+  virtual void CopyCaptureToVideoFrame(

[Pawel Osciak, 2013/08/24 01:29:31]

What happens on error? I assume we get NotifyError after TryCapture. Do we get
NotifyError after this call too?

What if we TryCapture(), then not receive NotifyError if it fails and do
CopyCaptureToVideoFrame()? We get two NotifyError()s?

[sheu, 2013/08/26 21:30:52]

We should be getting NotifyError always on error condition.  So if TryCapture
fails for platform reasons (not just a we-tried-but-couldn't-do-it-at-this-time,
we'd get a NotifyError for that.  And then a subsequent attempt at
CopyCaptureToVideoFrame() could fail separately, if it couldn't copy from the
cached contents, creating another NotifyError callback.

I don't think this is unusual?

+      const scoped_refptr<media::VideoFrame>& frame) = 0;
+
+  // Destroys the capturer; all pending inputs and outputs are dropped
+  // immediately and the component is freed.  This call may asynchronously free
+  // system resources, but its client-visible effects are synchronous.  After
+  // this method returns no more callbacks will be made on the client.  Deletes
+  // |this| unconditionally, so make sure to drop all pointers to it!
+  virtual void Destroy() = 0;
+
+  virtual ~SurfaceCapturer();
+};
+
+}  // namespace content
+
+#endif  // CONTENT_COMMON_GPU_SURFACE_CAPTURER_H_