ppapi/utility/graphics/paint_aggregator.h

   1 // Copyright (c) 2011 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_AGGREGATOR_H_
   6 #define PPAPI_UTILITY_GRAPHICS_PAINT_AGGREGATOR_H_
   7
   8 #include <stddef.h>
   9 #include <vector>
  10
  11 #include "ppapi/cpp/point.h"
  12 #include "ppapi/cpp/rect.h"
  13
  14 /// @file
  15 /// This file defines the API to aggregate multiple invalidation and scroll
  16 /// commands to produce a scroll and repaint sequence.
  17 namespace pp {
  18
  19 /// This class is responsible for aggregating multiple invalidation and scroll
  20 /// commands to produce a scroll and repaint sequence. You can use this manually
  21 /// to track your updates, but most applications will use the PaintManager to
  22 /// additionally handle the necessary callbacks on top of the PaintAggregator
  23 /// functionality.
  24 ///
  25 /// Refer to <code>http://code.google.com/p/ppapi/wiki/2DPaintingModel</code>
  26 /// for further information.
  27 class PaintAggregator {
  28  public:
  29   struct PaintUpdate {
  30     /// Default constructor for creating an is_null() <code>PaintUpdate</code>
  31     /// object.
  32     PaintUpdate();
  33
  34     /// Destructor.
  35     ~PaintUpdate();
  36
  37     /// True if there is a scroll applied. This indicates that the scroll delta
  38     /// and scroll_rect are nonzero (just as a convenience).
  39     bool has_scroll;
  40
  41     /// The amount to scroll by. Either the X or Y may be nonzero to indicate a
  42     /// scroll in that direction, but there will never be a scroll in both
  43     /// directions at the same time (this will be converted to a paint of the
  44     /// region instead).
  45     ///
  46     /// If there is no scroll, this will be (0, 0).
  47     Point scroll_delta;
  48
  49     /// The rectangle that should be scrolled by the scroll_delta. If there is
  50     /// no scroll, this will be (0, 0, 0, 0). We only track one scroll command
  51     /// at once. If there are multiple ones, they will be converted to
  52     /// invalidates.
  53     Rect scroll_rect;
  54
  55     /// A list of all the individual dirty rectangles. This is an aggregated
  56     /// list of all invalidate calls. Different rectangles may be unified to
  57     /// produce a minimal list with no overlap that is more efficient to paint.
  58     /// This list also contains the region exposed by any scroll command.
  59     std::vector<Rect> paint_rects;
  60
  61     /// The union of all paint_rects.
  62     Rect paint_bounds;
  63   };
  64
  65   /// Default constructor.
  66   PaintAggregator();
  67
  68   /// Setter function setting the max ratio of paint rect area to scroll rect
  69   /// area that we will tolerate before downgrading the scroll into a repaint.
  70   ///
  71   /// If the combined area of paint rects contained within the scroll
  72   /// rect grows too large, then we might as well just treat
  73   /// the scroll rect as a paint rect.
  74   ///
  75   /// @param[in] area The max ratio of paint rect area to scroll rect area that
  76   /// we will tolerate before downgrading the scroll into a repaint.
  77   void set_max_redundant_paint_to_scroll_area(float area) {
  78     max_redundant_paint_to_scroll_area_ = area;
  79   }
  80
  81   /// Setter function for setting the maximum number of paint rects. If we
  82   /// exceed this limit, then we'll start combining paint rects (see
  83   /// CombinePaintRects). This limiting can be important since there is
  84   /// typically some overhead in deciding what to paint. If your module is fast
  85   /// at doing these computations, raise this threshold, if your module is
  86   /// slow, lower it (probably requires some tuning to find the right value).
  87   ///
  88   /// @param[in] max_rects The maximum number of paint rects.
  89   void set_max_paint_rects(size_t max_rects) {
  90     max_paint_rects_ = max_rects;
  91   }
  92
  93   /// This function determines if there is a pending update. There is a
  94   /// PendingUpdate if InvalidateRect or ScrollRect were called and
  95   /// ClearPendingUpdate was not called.
  96   ///
  97   /// @return true if there is a pending update, otherwise false.
  98   bool HasPendingUpdate() const;
  99
 100   /// This function clears a pending update.
 101   void ClearPendingUpdate();
 102
 103   /// This function gets a pending update.
 104   ///
 105   /// @return A PaintUpdate containing the pending update.
 106   PaintUpdate GetPendingUpdate() const;
 107
 108   /// This function invalidates the rect so it will be repainted.
 109   ///
 110   /// @param[in] rect A rect to be repainted.
 111   void InvalidateRect(const Rect& rect);
 112
 113   /// This function adds a pending scroll update.
 114   ///
 115   /// @param[in] clip_rect The rect to scroll.
 116   /// @param[in] amount A Point amount to scroll <code>rect</code>.
 117   void ScrollRect(const Rect& clip_rect, const Point& amount);
 118
 119  private:
 120   // This structure is an internal version of PaintUpdate. It's different in
 121   // two respects:
 122   //
 123   //  - The scroll damange (area exposed by the scroll operation, if any) is
 124   //    maintained separately from the dirty rects generated by calling
 125   //    InvalidateRect. We need to know this distinction for some operations.
 126   //
 127   //  - The paint bounds union is computed on the fly so we don't have to keep
 128   //    a rectangle up-to-date as we do different operations.
 129   class InternalPaintUpdate {
 130    public:
 131     InternalPaintUpdate();
 132     ~InternalPaintUpdate();
 133
 134     // Computes the rect damaged by scrolling within |scroll_rect| by
 135     // |scroll_delta|. This rect must be repainted. It is not included in
 136     // paint_rects or in the rect returned by GetPaintBounds.
 137     Rect GetScrollDamage() const;
 138
 139     // Returns the smallest rect containing all paint rects, not including the
 140     // scroll damage rect.
 141     Rect GetPaintBounds() const;
 142
 143     Point scroll_delta;
 144     Rect scroll_rect;
 145
 146     // Does not include the scroll damage rect.
 147     std::vector<Rect> paint_rects;
 148   };
 149
 150   Rect ScrollPaintRect(const Rect& paint_rect, const Point& amount) const;
 151   bool ShouldInvalidateScrollRect(const Rect& rect) const;
 152   void InvalidateScrollRect();
 153   void CombinePaintRects();
 154
 155   InternalPaintUpdate update_;
 156
 157   // If the combined area of paint rects contained within the scroll rect grows
 158   // too large, then we might as well just treat the scroll rect as a paint
 159   // rect. This constant sets the max ratio of paint rect area to scroll rect
 160   // area that we will tolerate before downgrading the scroll into a repaint.
 161   float max_redundant_paint_to_scroll_area_;
 162
 163   // The maximum number of paint rects. If we exceed this limit, then we'll
 164   // start combining paint rects (see CombinePaintRects). This limiting can be
 165   // important since there is typically some overhead in deciding what to
 166   // paint. If your plugin is fast at doing these computations, raise this
 167   // threshold, if your plugin is slow, lower it (probably requires some
 168   // tuning to find the right value).
 169   size_t max_paint_rects_;
 170 };
 171
 172 }  // namespace pp
 173
 174 #endif  // PPAPI_UTILITY_PAINT_AGGREGATOR_H_