Region is a compressed one bit mask. Region describes an aliased clipping area on integer boundaries. Region can also describe an array of integer rectangles.
Canvas uses Region to reduce the current clip. Region may be drawn to Canvas; Paint determines if Region is filled or stroked, its Color, and so on.
Region may be constructed from IRect array or Path. Diagonal lines and curves in Path become integer rectangle edges. Regions operators compute union, intersection, difference, and so on. Canvas allows only intersection and difference; successive clips can only reduce available Canvas area.
SkRegion describes the set of pixels used to clip Canvas. SkRegion is compact, efficiently storing a single integer rectangle, or a run length encoded array of rectangles. SkRegion may reduce the current Canvas Clip, or may be drawn as one or more integer rectangles. SkRegion iterator returns the scan lines or rectangles contained by it, optionally intersecting a bounding rectangle.
SkRegion related constants are defined by enum, enum class, #define, const, and constexpr.
SkRegion uses C++ classes to declare the public data structures and interfaces.
SkRegion can be constructed or initialized by these functions, including C++ class constructors.
SkRegion operators inline class member functions with arithmetic equivalents.
SkRegion member functions read and modify the structure properties.
SkRegion::Iterator can be constructed or initialized by these functions, including C++ class constructors.
SkRegion::Iterator member functions read and modify the structure properties.
Returns sequence of rectangles, sorted along y-axis, then x-axis, that make up Region.
Initializes Iterator with an empty Region. done on Iterator returns true. Call reset to initialized Iterator at a later time.
empty Region ierator
rect={1,2,3,4}
reset SkRegion
Sets Iterator to return elements of IRect array in region.
Region iterator
rect={1,2,3,4}
reset SkRegion Cliperator Spanerator
Points Iterator to start of Region. Returns true if Region was set; otherwise, returns false.
true if Region was set
#Volatile
empty iter rewind success=false
empty iter rect={0,0,0,0}
empty region rewind success=true
empty region rect={0,0,0,0}
after set rect rect={1,2,3,4}
after rewind rewind success=true
after rewind rect={1,2,3,4}
reset
Resets iterator, using the new Region.
empty region: done=true after set rect: done=true after reset: done=false
rewind
Returns true if Iterator is pointing to final IRect in Region.
true if data parsing is complete
done=true done=false
next rect
Advances Iterator to next IRect in Region if it is not done.
rect={1,2,3,4}
rect={5,6,7,8}
done rect
Returns IRect element in Region. Does not return predictable results if Region is empty.
part of Region as IRect
#Volatile
rect={0,0,0,0}
rect={1,2,3,4}
next done
Returns Region if set; otherwise, returns nullptr.
iterated Region
Iterator reset
SkRegion::Cliperator can be constructed or initialized by these functions, including C++ class constructors.
SkRegion::Cliperator member functions read and modify the structure properties.
Returns the sequence of rectangles, sorted along y-axis, then x-axis, that make up Region intersected with the specified clip rectangle.
Sets Cliperator to return elements of IRect array in Region within clip.
Region iterator
rect={1,2,2,3}
SkRegion Iterator Spanerator
Returns true if Cliperator is pointing to final IRect in Region.
true if data parsing is complete
empty region done=true after add rect done=false
next rect
Advances iterator to next IRect in Region contained by clip.
rect={1,3,3,4}
rect={5,6,7,7}
done
Returns IRect element in Region, intersected with clip passed to Cliperator constructor. Does not return predictable results if Region is empty.
part of Region inside clip as IRect
#Volatile
empty region rect={1094713344,1065353216,0,-1}
after set rect rect={1,2,3,3}
next done
SkRegion::Spanerator can be constructed or initialized by these functions, including C++ class constructors.
SkRegion::Spanerator member functions read and modify the structure properties.
Returns the line segment ends within Region that intersect a horizontal line.
Sets Spanerator to return line segments in Region on scan line.
Region iterator
SkRegion Iterator Cliperator
Advances iterator to next span intersecting Region within line segment provided in constructor. Returns true if interval was found.
true if interval was found
empty region: result=false after set rect: result=true left=2 right=3
done
Constructs an empty Region. Region is set to empty bounds at (0, 0) with zero width and height.
empty Region
region bounds: {0, 0, 0, 0}
setEmpty
Constructs a copy of an existing region. Copy constructor makes two regions identical by value. Internally, region and the returned result share pointer values. The underlying Rect array is copied when modified.
Creating a Region copy is very efficient and never allocates memory. Regions are always copied by value from the interface; the underlying shared pointers are not exposed.
copy of Region
region bounds: {1,2,3,4}
region2 bounds: {1,2,3,4}
after region set empty:
region bounds: {0,0,0,0}
region2 bounds: {1,2,3,4}
setRegion operator=(const SkRegion& region)
Constructs a rectangular Region matching the bounds of rect.
rectangular Region
setRect[2] setRegion
Releases ownership of any shared data and deletes data if Region is sole owner.
region2 bounds: {1,2,3,4}
SkRegion() SkRegion(const SkRegion& region) SkRegion(const SkIRect& rect) operator=(const SkRegion& region)
Constructs a copy of an existing region. Makes two regions identical by value. Internally, region and the returned result share pointer values. The underlying Rect array is copied when modified.
Creating a Region copy is very efficient and never allocates memory. Regions are always copied by value from the interface; the underlying shared pointers are not exposed.
Region to copy by value
region1 bounds: {1,2,3,4}
region2 bounds: {1,2,3,4}
set swap SkRegion(const SkRegion& region)
Compares Region and other; returns true if they enclose exactly the same area.
true if Region pair are equivalent
empty one == two set rect one != two set empty one == two
operator!=(const SkRegion& other) const operator=(const SkRegion& region)
Compares Region and other; returns true if they do not enclose the same area.
true if Region pair are not equivalent
empty one == two set rect one != two union rect one == two
operator==(const SkRegion& other) const operator=(const SkRegion& region)
Sets Region to src, and returns true if src bounds is not empty. This makes Region and src identical by value. Internally, Region and src share pointer values. The underlying Rect array is copied when modified.
Creating a Region copy is very efficient and never allocates memory. Regions are always copied by value from the interface; the underlying shared pointers are not exposed.
copy of src
region1 bounds: {1,2,3,4}
region2 bounds: {1,2,3,4}
operator=(const SkRegion& region) swap SkRegion(const SkRegion& region)
Exchanges IRect array of Region and other. swap internally exchanges pointers, so it is lightweight and does not allocate memory.
swap usage has largely been replaced by operator=(const SkRegion& region). Paths do not copy their content on assignment until they are written to, making assignment as efficient as swap.
region1 bounds: {0,0,0,0}
region2 bounds: {1,2,3,4}
operator=(const SkRegion& region) set SkRegion(const SkRegion& region)
Returns true if Region is empty. Empty Region has bounds width or height less than or equal to zero. SkRegion() constructs empty Region; setEmpty and setRect with dimensionless data make Region empty.
true if bounds has no width or height
initial: region is empty set rect: region is not empty set empty: region is empty
isRect isComplex operator==(const SkRegion& other) const
Returns true if Region is one IRect with positive dimensions.
true if Region contains one IRect
initial: region is not rect set rect: region is rect set empty: region is not rect
isEmpty isComplex
Returns true if Region is described by more than one rectangle.
true if Region contains more than one IRect
initial: region is not complex set rect: region is not complex op rect: region is complex
isEmpty isRect
Returns minimum and maximum axes values of IRect array. Returns (0, 0, 0, 0) if Region is empty.
combined bounds of all IRect elements
bounds: {1,2,4,5}
isEmpty isRect
Returns a value that increases with the number of elements in Region. Returns zero if Region is empty. Returns one if Region equals IRect; otherwise, returns value greater than one indicating that Region is complex.
Call to compare Regions for relative complexity.
relative complexity
initial: region complexity 0 set rect: region complexity 1 op rect: region complexity 3
isRect isComplex
Appends outline of Region to path. Returns true if Region is not empty; otherwise, returns false, and leaves path unmodified.
true if path changed
isEmpty isComplex
Constructs an empty Region. Region is set to empty bounds at (0, 0) with zero width and height. Always returns false.
false
region bounds: {1,2,3,4}
after region set empty:
region bounds: {0,0,0,0}
SkRegion()
Constructs a rectangular Region matching the bounds of rect. If rect is empty, constructs empty and returns false.
true if rect is not empty
region is not empty region is empty setEmpty: false
SkRegion(const SkIRect& rect)
Constructs Region with bounds (left, top, right, bottom). Returns true if left is less than right and top is less than bottom; otherwise, constructs empty Region and returns false.
rectangular Region
set to: 1,2,3,4: success:true {1,2,3,4}
set to: 3,2,1,4: success:false {0,0,0,0}
SkRegion(const SkIRect& rect)
Constructs Region as the union of IRect in rects array. If count is zero, constructs empty Region. Returns false if constructed Region is empty.
May be faster than repeated calls to op.
true if constructed Region is not empty
setRect[2] op[2][3][4][5][6]
Constructs a copy of an existing region. Makes two regions identical by value. Internally, region and the returned result share pointer values. The underlying Rect array is copied when modified.
Creating a Region copy is very efficient and never allocates memory. Regions are always copied by value from the interface; the underlying shared pointers are not exposed.
Region to copy by value
region bounds: {1,2,3,4}
region2 bounds: {1,2,3,4}
after region set empty:
region bounds: {1,2,3,4}
region2 bounds: {0,0,0,0}
SkRegion(const SkRegion& region)
Constructs Region to match outline of path within clip. Returns false if constructed Region is empty.
Constructed Region draws the same pixels as path through clip when Anti Aliasing is disabled.
true if constructed Region is not empty
setRects op[2][3][4][5][6]
Returns true if Region intersects rect. Returns false if either rect or Region is empty, or do not intersect.
true if rect and Region have area in common
contains[2][3] SkRect::intersects[2]
Returns true if Region intersects other. Returns false if either other or Region is empty, or do not intersect.
true if other and Region have area in common
contains[2][3] SkRect::intersects[2]
Returns true if IPoint (x, y) is inside Region. Returns false if Region is empty.
true if (x, y) is inside Region
intersects[2] SkRect::contains[2][3]
Returns true if other is completely inside Region. Returns false if Region or other is empty.
true if other is inside Region
intersects[2] SkRect::contains[2][3]
Returns true if other is completely inside Region. Returns false if Region or other is empty.
true if other is inside Region
intersects[2] SkRect::contains[2][3]
Returns true if Region is a single rectangle and contains r. May return false even though Region contains r.
true quickly if r points are equal or inside
quickContains 1: true quickContains 2: true quickContains 3: false
contains[2][3] quickReject[2] intersects[2]
Returns true if Region is a single rectangle and contains IRect (left, top, right, bottom). Returns false if Region is empty or IRect (left, top, right, bottom) is empty. May return false even though Region contains (left, top, right, bottom).
true quickly if IRect are equal or inside
quickContains 1: true quickContains 2: true quickContains 3: false
contains[2][3] quickReject[2] intersects[2]
Returns true if Region does not intersect rect. Returns true if rect is empty or Region is empty. May return false even though Region does not intersect rect.
true if rect does not intersect
quickReject 1: true quickReject 2: true quickReject 3: false
quickContains[2] contains[2][3] intersects[2]
Returns true if Region does not intersect rgn. Returns true if rgn is empty or Region is empty. May return false even though Region does not intersect rgn.
true if rgn does not intersect
quickReject 1: true quickReject 2: true quickReject 3: false
quickContains[2] contains[2][3] intersects[2]
Offsets Region by IVector (dx, dy). Has no effect if Region is empty.
SkCanvas::translate SkIRect::offset[2] SkPath::offset[2]
Offsets Region by IVector (dx, dy), writing result to dst. Region may be passed as dst parameter, translating Region in place. Has no effect if dst is nullptr. If Region is empty, sets dst to empty.
SkCanvas::translate SkIRect::offset[2] SkPath::offset[2]
The logical operations that can be performed when combining two Regions.
SkPathOp
Replaces Region with the result of Region op rect. Returns true if replaced Region is not empty.
false if result is empty
setRects Op
Replaces Region with the result of Region op IRect (left, top, right, bottom). Returns true if replaced Region is not empty.
false if result is empty
setRects Op
Replaces Region with the result of Region op rgn. Returns true if replaced Region is not empty.
false if result is empty
setRects Op
Replaces Region with the result of rect op rgn. Returns true if replaced Region is not empty.
false if result is empty
setRects Op
Replaces Region with the result of rgn op rect. Returns true if replaced Region is not empty.
false if result is empty
setRects Op
Replaces Region with the result of rgna op rgnb. Returns true if replaced Region is not empty.
false if result is empty
setRects Op
string representation of Region
Writes Region to buffer, and returns number of bytes written. If buffer is nullptr, returns number number of bytes that would be written.
size of Region
readFromMemory
Constructs Region from buffer of size length. Returns bytes read. Returned value will be multiple of four or zero if length was too small.
bytes read
writeToMemory