ui: Add ScheduleOverlayPlane API to GLImage.

ui/gl/gl_image.h

Index: ui/gl/gl_image.h
diff --git a/ui/gl/gl_image.h b/ui/gl/gl_image.h
index 45303fd64602321259973a4090478e645390ca37..4b1e9da3786d869083f19ccc5dd45539a4fbec1d 100644
--- a/ui/gl/gl_image.h
+++ b/ui/gl/gl_image.h
@@ -6,6 +6,9 @@
 #define UI_GL_GL_IMAGE_H_
 
 #include "base/memory/ref_counted.h"
+#include "ui/gfx/overlay_transform.h"
+#include "ui/gfx/rect.h"
+#include "ui/gfx/rect_f.h"
 #include "ui/gfx/size.h"
 #include "ui/gl/gl_export.h"
 
@@ -41,6 +44,20 @@ class GL_EXPORT GLImage : public base::RefCounted<GLImage> {
   // Called after the texture image data has been modified.
   virtual void DidModifyTexImage() = 0;
 
+  // Schedule image as an overlay plane to be shown at swap time.
+  // |z_order| specifies the stacking order of the plane relative to the
+  // main framebuffer located at index 0. For the case where there is no
+  // main framebuffer, overlays may be scheduled at 0, taking its place.
+  // |transform| specifies how the buffer is to be transformed during
+  // composition.
+  // |bounds_rect| specify where it is supposed to be on the screen in pixels.
+  // |crop_rect| specifies the region within the buffer to be placed inside
+  // |bounds_rect|.
+  virtual bool ScheduleOverlayPlane(int z_order,
+                                    OverlayTransform transform,
+                                    const Rect& bounds_rect,
+                                    const RectF& crop_rect) = 0;

[piman, 2014/07/30 20:11:42]

I'm not sure how this API works without extra context... E.g. how do we choose
which window or screen this is going to go to.
Shouldn't there be some connection with the GLSurface, since that's what gets
the SwapBuffers, which is what activates the overlay?

What is the semantics wrt statefulness? Is an image bound to an overlay from the
next swap until another image replaces it a the same z index? Or is the
expectation that at each frame the full set of overlays is respecified? If the
former, how do you disable an overlay?

[alexst (slow to review), 2014/07/30 20:21:48]

Re: extra context, I just commented on that before I saw your message. We'll
need the current GLSurface's AcceleratedWidget to get that. We can add that API
to the surface now or address as a followup.

Re: statefullness, the expectation is that the full set of overlays is
respecified on each swap.

+
   // Indicate that image should be released after use.
   // (For an Android work-around only).
   virtual void SetReleaseAfterUse();