ppapi/utility/graphics/paint_manager.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_UTILITY_GRAPHICS_PAINT_MANAGER_H_
   6 #define PPAPI_UTILITY_GRAPHICS_PAINT_MANAGER_H_
   7
   8 #include <vector>
   9
  10 #include "ppapi/cpp/graphics_2d.h"
  11 #include "ppapi/utility/completion_callback_factory.h"
  12 #include "ppapi/utility/graphics/paint_aggregator.h"
  13
  14 /// @file
  15 /// This file defines the API to convert the "plugin push" model of painting
  16 /// in PPAPI to a paint request at a later time.
  17
  18 namespace pp {
  19
  20 class Graphics2D;
  21 class Instance;
  22 class Point;
  23 class Rect;
  24
  25 /// This class converts the "instance push" model of painting in PPAPI to a
  26 /// paint request at a later time. Usage is that you call Invalidate and
  27 /// Scroll, and implement the Client interface. Your OnPaint handler will
  28 /// then get called with coalesced paint events.
  29 ///
  30 /// This class is basically a <code>PaintAggregator</code> that groups updates,
  31 /// plus management of callbacks for scheduling paints.
  32 ///
  33 /// <strong>Example:</strong>
  34 ///
  35 /// <code>
  36 ///
  37 ///  class MyClass : public pp::Instance, public PaintManager::Client {
  38 ///   public:
  39 ///    MyClass() {
  40 ///      paint_manager_.Initialize(this, this, false);
  41 ///    }
  42 ///
  43 ///    void ViewChanged(const pp::Rect& position, const pp::Rect& clip) {
  44 ///      paint_manager_.SetSize(position.size());
  45 ///    }
  46 ///
  47 ///    void DoSomething() {
  48 ///      // This function does something like respond to an event that causes
  49 ///      // the screen to need updating.
  50 ///      paint_manager_.InvalidateRect(some_rect);
  51 ///    }
  52 ///
  53 ///    // Implementation of PaintManager::Client
  54 ///    virtual bool OnPaint(pp::Graphics2D& device,
  55 ///                         const pp::PaintUpdate& update) {
  56 ///      // If our app needed scrolling, we would apply that first here.
  57 ///
  58 ///      // Then we would either repaint the area returned by GetPaintBounds or
  59 ///      // iterate through all the paint_rects.
  60 ///
  61 ///      // The caller will call Flush() for us, so don't do that here.
  62 ///      return true;
  63 ///    }
  64 ///
  65 ///   private:
  66 ///    pp::PaintManager paint_manager_;
  67 ///  };
  68 /// </code>
  69 class PaintManager {
  70  public:
  71   class Client {
  72    public:
  73     /// OnPaint() paints the given invalid area of the instance to the given
  74     /// graphics device. Returns true if anything was painted.
  75     ///
  76     /// You are given the list of rects to paint in <code>paint_rects</code>,
  77     /// and the union of all of these rects in <code>paint_bounds</code>. You
  78     /// only have to paint the area inside each of the
  79     /// <code>paint_rects</code>, but can paint more if you want (some apps may
  80     /// just want to paint the union).
  81     ///
  82     /// Do not call Flush() on the graphics device, this will be done
  83     /// automatically if you return true from this function since the
  84     /// <code>PaintManager</code> needs to handle the callback.
  85     ///
  86     /// It is legal for you to cause invalidates inside of Paint which will
  87     /// then get executed as soon as the Flush for this update has completed.
  88     /// However, this is not very nice to the host system since it will spin the
  89     /// CPU, possibly updating much faster than necessary. It is best to have a
  90     /// 1/60 second timer to do an invalidate instead. This will limit your
  91     /// animation to the slower of 60Hz or "however fast Flush can complete."
  92     ///
  93     /// @param[in] graphics A <code>Graphics2D</code> to be painted.
  94     /// @param[in] paint_rects A list of rects to paint.
  95     /// @param[in] paint_bounds A union of the rects to paint.
  96     ///
  97     /// @return true if successful, otherwise false.
  98     virtual bool OnPaint(Graphics2D& graphics,
  99                          const std::vector<Rect>& paint_rects,
 100                          const Rect& paint_bounds) = 0;
 101
 102    protected:
 103     // You shouldn't be doing deleting through this interface.
 104     virtual ~Client() {}
 105   };
 106
 107   /// Default constructor for creating an is_null() <code>PaintManager</code>
 108   /// object. If you use this version of the constructor, you must call
 109   /// Initialize() below.
 110   PaintManager();
 111
 112   /// A constructor to create a new <code>PaintManager</code> with an instance
 113   /// and client.
 114   ///
 115   /// <strong>Note:</strong> You will need to call SetSize() before this class
 116   /// will do anything. Normally you do this from the <code>ViewChanged</code>
 117   /// method of your instance.
 118   ///
 119   /// @param instance The instance using this paint manager to do its
 120   /// painting. Painting will automatically go to this instance and you don't
 121   /// have to manually bind any device context (this is all handled by the
 122   /// paint manager).
 123   ///
 124   /// @param client A non-owning pointer and must remain valid (normally the
 125   /// object implementing the Client interface will own the paint manager).
 126   ///
 127   /// @param is_always_opaque A flag passed to the device contexts that this
 128   /// class creates. Set this to true if your instance always draws an opaque
 129   /// image to the device. This is used as a hint to the browser that it does
 130   /// not need to do alpha blending, which speeds up painting. If you generate
 131   /// non-opqaue pixels or aren't sure, set this to false for more general
 132   /// blending.
 133   ///
 134   /// If you set is_always_opaque, your alpha channel should always be set to
 135   /// 0xFF or there may be painting artifacts. Being opaque will allow the
 136   /// browser to do a memcpy rather than a blend to paint the plugin, and this
 137   /// means your alpha values will get set on the page backing store. If these
 138   /// values are incorrect, it could mess up future blending. If you aren't
 139   /// sure, it is always correct to specify that it it not opaque.
 140   PaintManager(Instance* instance, Client* client, bool is_always_opaque);
 141
 142   /// Destructor.
 143   ~PaintManager();
 144
 145   /// Initialize() must be called if you are using the 0-arg constructor.
 146   ///
 147   /// @param instance The instance using this paint manager to do its
 148   /// painting. Painting will automatically go to this instance and you don't
 149   /// have to manually bind any device context (this is all handled by the
 150   /// paint manager).
 151   /// @param client A non-owning pointer and must remain valid (normally the
 152   /// object implementing the Client interface will own the paint manager).
 153   /// @param is_always_opaque A flag passed to the device contexts that this
 154   /// class creates. Set this to true if your instance always draws an opaque
 155   /// image to the device. This is used as a hint to the browser that it does
 156   /// not need to do alpha blending, which speeds up painting. If you generate
 157   /// non-opqaue pixels or aren't sure, set this to false for more general
 158   /// blending.
 159   ///
 160   /// If you set <code>is_always_opaque</code>, your alpha channel should
 161   /// always be set to <code>0xFF</code> or there may be painting artifacts.
 162   /// Being opaque will allow the browser to do a memcpy rather than a blend
 163   /// to paint the plugin, and this means your alpha values will get set on the
 164   /// page backing store. If these values are incorrect, it could mess up
 165   /// future blending. If you aren't sure, it is always correct to specify that
 166   /// it it not opaque.
 167   void Initialize(Instance* instance, Client* client, bool is_always_opaque);
 168
 169   /// Setter function setting the max ratio of paint rect area to scroll rect
 170   /// area that we will tolerate before downgrading the scroll into a repaint.
 171   ///
 172   /// If the combined area of paint rects contained within the scroll
 173   /// rect grows too large, then we might as well just treat
 174   /// the scroll rect as a paint rect.
 175   ///
 176   /// @param[in] area The max ratio of paint rect area to scroll rect area that
 177   /// we will tolerate before downgrading the scroll into a repaint.
 178   void set_max_redundant_paint_to_scroll_area(float area) {
 179     aggregator_.set_max_redundant_paint_to_scroll_area(area);
 180   }
 181
 182   /// Setter function for setting the maximum number of paint rects. If we
 183   /// exceed this limit, then we'll start combining paint rects (refer to
 184   /// CombinePaintRects() for further information). This limiting can be
 185   /// important since there is typically some overhead in deciding what to
 186   /// paint. If your module is fast at doing these computations, raise this
 187   /// threshold, if your module is slow, lower it (probably requires some
 188   /// tuning to find the right value).
 189   ///
 190   /// @param[in] max_rects The maximum number of paint rects.
 191   void set_max_paint_rects(size_t max_rects) {
 192     aggregator_.set_max_paint_rects(max_rects);
 193   }
 194
 195   /// SetSize() sets the size of the instance. If the size is the same as the
 196   /// previous call, this will be a NOP. If the size has changed, a new device
 197   /// will be allocated to the given size and a paint to that device will be
 198   /// scheduled.
 199   ///
 200   /// This function is intended to be called from <code>ViewChanged</code> with
 201   /// the size of the instance. Since it tracks the old size and only allocates
 202   /// when the size changes, you can always call this function without worrying
 203   /// about whether the size changed or ViewChanged() is called for another
 204   /// reason (like the position changed).
 205   ///
 206   /// @param new_size The new size for the instance.
 207   void SetSize(const Size& new_size);
 208
 209   /// This function provides access to the underlying device in case you need
 210   /// it. If you have done a SetSize(), note that the graphics context won't be
 211   /// updated until right before the next call to OnPaint().
 212   ///
 213   /// <strong>Note:</strong> If you call Flush on this device the paint manager
 214   /// will get very confused, don't do this!
 215   const Graphics2D& graphics() const { return graphics_; }
 216
 217   /// This function provides access to the underlying device in case you need
 218   /// it. If you have done a SetSize(), note that the graphics context won't be
 219   /// updated until right before the next call to OnPaint().
 220   ///
 221   /// <strong>Note:</strong> If you call Flush on this device the paint manager
 222   /// will get very confused, don't do this!
 223   Graphics2D& graphics() { return graphics_; }
 224
 225   /// Invalidate() invalidate the entire instance.
 226   void Invalidate();
 227
 228   /// InvalidateRect() Invalidate the provided rect.
 229   ///
 230   /// @param[in] rect The <code>Rect</code> to be invalidated.
 231   void InvalidateRect(const Rect& rect);
 232
 233   /// ScrollRect() scrolls the provided <code>clip_rect</code> by the
 234   /// <code>amount</code> argument.
 235   ///
 236   /// @param clip_rect The clip rectangle to scroll.
 237   /// @param amount The amount to scroll <code>clip_rect</code>.
 238   void ScrollRect(const Rect& clip_rect, const Point& amount);
 239
 240   /// GetEffectiveSize() returns the size of the graphics context for the
 241   /// next paint operation. This is the pending size if a resize is pending
 242   /// (the instance has called SetSize() but we haven't actually painted it
 243   /// yet), or the current size of no resize is pending.
 244   ///
 245   /// @return The effective size.
 246   Size GetEffectiveSize() const;
 247
 248  private:
 249   // Disallow copy and assign (these are unimplemented).
 250   PaintManager(const PaintManager&);
 251   PaintManager& operator=(const PaintManager&);
 252
 253   // Makes sure there is a callback that will trigger a paint at a later time.
 254   // This will be either a Flush callback telling us we're allowed to generate
 255   // more data, or, if there's no flush callback pending, a manual call back
 256   // to the message loop via ExecuteOnMainThread.
 257   void EnsureCallbackPending();
 258
 259   // Does the client paint and executes a Flush if necessary.
 260   void DoPaint();
 261
 262   // Callback for asynchronous completion of Flush.
 263   void OnFlushComplete(int32_t result);
 264
 265   // Callback for manual scheduling of paints when there is no flush callback
 266   // pending.
 267   void OnManualCallbackComplete(int32_t);
 268
 269   Instance* instance_;
 270
 271   // Non-owning pointer. See the constructor.
 272   Client* client_;
 273
 274   bool is_always_opaque_;
 275
 276   CompletionCallbackFactory<PaintManager> callback_factory_;
 277
 278   // This graphics device will be is_null() if no graphics has been manually
 279   // set yet.
 280   Graphics2D graphics_;
 281
 282   PaintAggregator aggregator_;
 283
 284   // See comment for EnsureCallbackPending for more on how these work.
 285   bool manual_callback_pending_;
 286   bool flush_pending_;
 287
 288   // When we get a resize, we don't bind right away (see SetSize). The
 289   // has_pending_resize_ tells us that we need to do a resize for the next
 290   // paint operation. When true, the new size is in pending_size_.
 291   bool has_pending_resize_;
 292   Size pending_size_;
 293 };
 294
 295 }  // namespace pp
 296
 297 #endif  // PPAPI_UTILITY_GRAPHICS_PAINT_MANAGER_H_