Tab Capture: Backing store readbacks to YV12 VideoFrames.

content/public/browser/render_widget_host.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_PUBLIC_BROWSER_RENDER_WIDGET_HOST_H_
 #define CONTENT_PUBLIC_BROWSER_RENDER_WIDGET_HOST_H_
 
 #include "base/callback.h"
 #include "content/common/content_export.h"
 #include "content/public/browser/keyboard_listener.h"
@@ skipping 10 matching lines @@
 #elif defined(OS_MACOSX)
 #include "skia/ext/platform_device.h"
 #endif
 
 class SkBitmap;
 
 namespace gfx {
 class Rect;
 }
 
+namespace media {
+class VideoFrame;
+}
+
 namespace content {
 
 class RenderProcessHost;
 class RenderWidgetHostImpl;
 class RenderWidgetHostView;
 
 // A RenderWidgetHost manages the browser side of a browser<->renderer
 // HWND connection.  The HWND lives in the browser process, and
 // windows events are sent over IPC to the corresponding object in the
 // renderer.  The renderer paints into shared memory, which we
@@ skipping 120 matching lines @@
 
   virtual void Focus() = 0;
   virtual void Blur() = 0;
 
   // Sets whether the renderer should show controls in an active state.  On all
   // platforms except mac, that's the same as focused. On mac, the frontmost
   // window will show active controls even if the focus is not in the web
   // contents, but e.g. in the omnibox.
   virtual void SetActive(bool active) = 0;
 
-  // Copies the given subset of the backing store, and passes the result as a
-  // bitmap to a callback.
+  // Copies the given subset of the backing store, and passes the result as an
+  // ARGB bitmap to a callback.
   //
   // If |src_rect| is empty, the whole contents is copied. If non empty
   // |accelerated_dst_size| is given and accelerated compositing is active, the
   // content is shrunk so that it fits in |accelerated_dst_size|. If
   // |accelerated_dst_size| is larger than the content size, the content is not
   // resized. If |accelerated_dst_size| is empty, the size copied from the
   // source contents is used. |callback| is invoked with true on success, false
   // otherwise, along with a SkBitmap containing the copied pixel data.
   //
   // NOTE: |callback| is called synchronously if the backing store is available.
   // When accelerated compositing is active, |callback| may be called
   // asynchronously.
   virtual void CopyFromBackingStore(
       const gfx::Rect& src_rect,
       const gfx::Size& accelerated_dst_size,
       const base::Callback<void(bool, const SkBitmap&)>& callback) = 0;
 #if defined(TOOLKIT_GTK)
   // Paint the backing store into the target's |dest_rect|.
   virtual bool CopyFromBackingStoreToGtkWindow(const gfx::Rect& dest_rect,
                                                GdkWindow* target) = 0;
 #elif defined(OS_MACOSX)
   virtual gfx::Size GetBackingStoreSize() = 0;
   virtual bool CopyFromBackingStoreToCGContext(const CGRect& dest_rect,
                                                CGContextRef target) = 0;
 #endif
+  // Returns true if CopyFromBackingStoreToVideoFrame is possible on the current

[scherkus (not reviewing), 2013/02/05 22:40:44]

nit: add () to function names referenced in comments

[ncarter (slow), 2013/02/06 23:54:44]

Done.

+  // backing store. Depends on platform support and compositor state. Callers
+  // should check this before each call to CopyFromBackingStoreToVideoFrame().

[scherkus (not reviewing), 2013/02/05 22:40:44]

can we promote this "should" into a "must" and have CFBSTVF() crash if you
didn't check?

it appears that the behaviour today is to return an empty frame, which can lead
to problems -- refer to my other comment:
https://codereview.chromium.org/12090109/diff/35001/ui/surface/accelerated_su...

[ncarter (slow), 2013/02/06 23:54:44]

Thanks for sharing your experience (which sounds hard-won) about empty frames
possibly leading to trouble. As mentioned in another comment, I am moving to a
"bool success" param with a caller-allocated VideoFrame, which will eliminate
the need to synthesize empty frames.

Callers have to handle failure invocations of the callback, and the case
discussed here is just one (avoidable) case. Your suggestions about crashing the
browser don't mesh with either my instincts, or the recommendations here:
http://dev.chromium.org/developers/coding-style ["Use CHECK() if the consequence
of a failed assertion would be a security vulnerability, where crashing the
browser is preferable.  Because this takes down the whole browser, sometimes
there are better options than CHECK()."] I think NOTREACHED() is appropriate for
cases like this.

[scherkus (not reviewing), 2013/02/07 18:25:03]

SGTM

+  virtual bool CanCopyToVideoFrame() const = 0;
+  // Copies a given subset of the backing store into a YV12 VideoFrame, and pass

[scherkus (not reviewing), 2013/02/05 22:40:44]

nit: blank line before comments to avoid walloftext

[ncarter (slow), 2013/02/06 23:54:44]

Done.

+  // it to the callback. The resulting VideoFrame will always be exactly
+  // |dst_size|. If |src_rect| does not match |dst_size|, the copied content
+  // will be scaled and letterboxed with black borders. Callbacks are permitted
+  // to take a refcount on the resulting VideoFrame for further processing on
+  // other threads.
+  //
+  // CopyFromBackingStoreToVideoFrame is not always possible. Callers should
+  // check the return value of CanCopyToVideoFrame(), and if false, fall back to
+  // a different method such as CopyFromBackingStore.
+  virtual void CopyFromBackingStoreToVideoFrame(
+      const gfx::Rect& src_rect,
+      const gfx::Size& dst_size,
+      const base::Callback<void(media::VideoFrame*)>& callback) = 0;
 
   // Send a command to the renderer to turn on full accessibility.
   virtual void EnableFullAccessibilityMode() = 0;
 
   // Forwards the given message to the renderer. These are called by
   // the view when it has received a message.
   virtual void ForwardMouseEvent(
       const WebKit::WebMouseEvent& mouse_event) = 0;
   virtual void ForwardWheelEvent(
       const WebKit::WebMouseWheelEvent& wheel_event) = 0;
@@ skipping 72 matching lines @@
   // within content/.  This method is necessary because
   // RenderWidgetHost is the root of a diamond inheritance pattern, so
   // subclasses inherit it virtually, which removes our ability to
   // static_cast to the subclass.
   virtual RenderWidgetHostImpl* AsRenderWidgetHostImpl() = 0;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_RENDER_WIDGET_HOST_H_