Documentation: SkCanvas API

site/user/api/skregion.md

+SkRegion
+========
+
+*Regions - set operations with rectangles*
+
+<!-- Updated Mar 4, 2011 -->
+
+Regions are a highly compressed way to represent (integer) areas. Skia
+uses them to represent (internally) the current clip on the
+canvas. Regions take their inspiration from the data type with the
+same name on the original Macintosh (thank you Bill).
+
+Regions are opaque structures, but they can be queried via
+iterators. Best of all, they can be combined with other regions and
+with rectangles (which can be thought of as "simple" regions. If you
+remember Set operations from math class (intersection, union,
+difference, etc.), then you're all ready to use regions.
+
+<!--?prettify lang=cc?-->
+
+    bool SkRegion::isEmpty();
+    bool SkRegion::isRect();
+    bool SkRegion::isComplex();
+
+Regions can be classified into one of three types: empty, rectangular,
+or complex.
+
+Empty regions are just that, empty. All empty regions are equal (using
+operator==). Compare this to rectangles (SkRect or SkIRect). Any
+rectangle with fLeft >= fRight or fTop >= fBottom is consider empty,
+but clearly there are different empty rectangles that are not equal.
+
+<!--?prettify lang=cc?-->
+
+    SkRect a = { 0, 0, 0, 0 };
+    SkRect b = { 1, 1, 1, 1 };
+
+Both a and b are empty, but they are definitely not equal to each
+other. However, with regions, all empty regions are equal. If you
+query its bounds, you will always get { 0, 0, 0, 0 }. Even if you
+translate it, it will still be all zeros.
+
+<!--?prettify lang=cc?-->
+
+<!--?prettify lang=cc?-->
+
+    SkRegion a, b;   // regions default to empty
+    assert(a == b);
+    a.offset(10, 20);
+    assert(a == b);
+    assert(a.getBounds() == { 0, 0, 0, 0 });   // not legal C++, but you get the point
+    assert(b.getBounds() == { 0, 0, 0, 0 });
+
+To initialize a region to something more interesting, use one of the
+set() methods
+
+<!--?prettify lang=cc?-->
+
+    SkRegion a, b;
+    a.setRect(10, 10, 50, 50);
+    b.setRect(rect);    // see SkIRect
+    c.setPath(path);   // see SkPath
+
+This is the first step that SkCanvas performs when one of its
+clip...() methods are called. The clip data is first transformed into
+device coordinates (see SkMatrix), and then a region is build from the
+data (either a rect or a path). The final step is to combine this new
+region with the existing clip using the specified operator.
+
+<!--?prettify lang=cc?-->
+
+    enum Op {
+        kUnion_Op,
+        kIntersect_Op,
+        kDifference_Op,
+        kXor_Op,
+        kReverseDifference_Op,
+        kReplace_Op
+    };
+
+By default, intersect op is used when a clip call is made, but the
+other operators are equally valid.
+
+<!--?prettify lang=cc?-->
+
+    // returns true if the resulting clip is non-empty (i.e. drawing can
+    // still occur)
+    bool SkCanvas::clipRect(const SkRect& rect, SkRegion::Op op) {
+        SkRegion rgn;
+    
+        // peek at the CTM (current transformation matrix on the canvas)
+        const SkMatrix& m = this->getTotalMatrix();
+    
+        if (m.rectStaysRect()) {    // check if a transformed rect can be
+                                    // represented as another rect
+
+            SkRect deviceRect;
+            m.mapRect(&deviceRect, rect);
+            SkIRect intRect;
+            deviceRect.round(&intRect);
+            rgn.setRect(intRect);
+        } else {  // matrix rotates or skew (or is perspective)
+            SkPath path;
+            path.addRect(rect);
+            path.transform(m);
+            rgn.setPath(path);
+        }
+    
+        // now combine the new region with the current one, using the specified *op*
+        return fCurrentClip.op(rgn, op);
+    }