ui: Add ScheduleOverlayPlane API to GLImage.

ui/gl/gl_image.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 UI_GL_GL_IMAGE_H_
 #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"
 
 namespace gfx {
 
 // Encapsulates an image that can be bound to a texture, hiding platform
 // specific management.
 class GL_EXPORT GLImage : public base::RefCounted<GLImage> {
  public:
   GLImage();
@@ skipping 15 matching lines @@
 
   // Called after the texture has been used for drawing.
   virtual void DidUseTexImage() = 0;
 
   // Called before the texture image data will be modified.
   virtual void WillModifyTexImage() = 0;
 
   // 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();
 
  protected:
   virtual ~GLImage();
 
  private:
   friend class base::RefCounted<GLImage>;
 
   DISALLOW_COPY_AND_ASSIGN(GLImage);
 };
 
 }  // namespace gfx
 
 #endif  // UI_GL_GL_IMAGE_H_