SkRegion Reference
===
# Region
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.
# Class SkRegion
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.
## Overview
## Constant
SkRegion related constants are defined by enum
, enum class
, #define
, const
, and constexpr
.
## Class
SkRegion uses C++ classes to declare the public data structures and interfaces.
## Constructor
SkRegion can be constructed or initialized by these functions, including C++ class constructors.
## Operator
SkRegion operators inline class member functions with arithmetic equivalents.
## Member Function
SkRegion member functions read and modify the structure properties.
# Class SkRegion::Iterator
## Constructor
SkRegion::Iterator can be constructed or initialized by these functions, including C++ class constructors.
## Member_Function
SkRegion::Iterator member functions read and modify the structure properties.
class Iterator {
public:
Iterator();
Iterator(const SkRegion& region);
bool rewind;
void reset(const SkRegion& region);
bool done const;
void next;
const SkIRect& rect;
const SkRegion* rgn;
};
Returns sequence of rectangles, sorted along y-axis, then x-axis, that make
up Region.
## Iterator
Iterator()
Initializes Iterator with an empty Region. done on Iterator returns true.
Call reset to initialized Iterator at a later time.
### Return Value
empty Region ierator
### Example
#### Example Output
~~~~
rect={1,2,3,4}
~~~~
### See Also
reset SkRegion
---
## Iterator
Iterator(const SkRegion& region)
Sets Iterator to return elements of IRect array in region.
### Parameters
### Return Value
Region iterator
### Example
#### Example Output
~~~~
rect={1,2,3,4}
~~~~
### See Also
reset SkRegion Cliperator Spanerator
---
## rewind
bool rewind()
Points Iterator to start of Region.
Returns true if Region was set; otherwise, returns false.
### Return Value
true if Region was set
### Example
#### Example Output
~~~~
#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}
~~~~
### See Also
reset
---
## reset
void reset(const SkRegion& region)
Resets iterator, using the new Region.
### Parameters
### Example
#### Example Output
~~~~
empty region: done=true
after set rect: done=true
after reset: done=false
~~~~
### See Also
rewind
---
## done
bool done() const
Returns true if Iterator is pointing to final IRect in Region.
### Return Value
true if data parsing is complete
### Example
#### Example Output
~~~~
done=true
done=false
~~~~
### See Also
next rect
---
## next
void next()
Advances Iterator to next IRect in Region if it is not done.
### Example
#### Example Output
~~~~
rect={1,2,3,4}
rect={5,6,7,8}
~~~~
### See Also
done rect
---
## rect
const SkIRect& rect() const
Returns IRect element in Region. Does not return predictable results if Region
is empty.
### Return Value
part of Region as IRect
### Example
#### Example Output
~~~~
#Volatile
rect={0,0,0,0}
rect={1,2,3,4}
~~~~
### See Also
next done
---
## rgn
const SkRegion* rgn() const
Returns Region if set; otherwise, returns nullptr.
### Return Value
iterated Region
### Example
### See Also
Iterator reset
---
# Class SkRegion::Cliperator
## Constructor
SkRegion::Cliperator can be constructed or initialized by these functions, including C++ class constructors.
## Member_Function
SkRegion::Cliperator member functions read and modify the structure properties.
Topic |
Description |
done |
returns if data parsing is complete |
next |
advances to next IRect within clip |
rect |
returns part of Region as IRect intersected with clip |
class SK_API Cliperator {
public:
Cliperator(const SkRegion& region, const SkIRect& clip);
bool done;
void next;
const SkIRect& rect const;
};
Returns the sequence of rectangles, sorted along y-axis, then x-axis, that make
up Region intersected with the specified clip rectangle.
## Cliperator
Cliperator(const SkRegion& region, const SkIRect& clip)
Sets Cliperator to return elements of IRect array in Region within clip.
### Parameters
### Return Value
Region iterator
### Example
#### Example Output
~~~~
rect={1,2,2,3}
~~~~
### See Also
SkRegion Iterator Spanerator
---
## done
bool done()
Returns true if Cliperator is pointing to final IRect in Region.
### Return Value
true if data parsing is complete
### Example
#### Example Output
~~~~
empty region done=true
after add rect done=false
~~~~
### See Also
next rect
---
## next
void next()
Advances iterator to next IRect in Region contained by clip.
### Example
#### Example Output
~~~~
rect={1,3,3,4}
rect={5,6,7,7}
~~~~
### See Also
done
---
## rect
const SkIRect& rect() const
Returns IRect element in Region, intersected with clip passed to Cliperator
constructor. Does not return predictable results if Region
is empty.
### Return Value
part of Region inside clip as IRect
### Example
#### Example Output
~~~~
#Volatile
empty region rect={1094713344,1065353216,0,-1}
after set rect rect={1,2,3,3}
~~~~
### See Also
next done
---
# Class SkRegion::Spanerator
## Constructor
SkRegion::Spanerator can be constructed or initialized by these functions, including C++ class constructors.
## Member_Function
SkRegion::Spanerator member functions read and modify the structure properties.
Topic |
Description |
next |
advances to next span on horizontal line |
class Spanerator {
public:
Spanerator(const SkRegion& region, int y, int left, int right);
bool next(int* left, int* right);
};
Returns the line segment ends within Region that intersect a horizontal line.
## Spanerator
Spanerator(const SkRegion& region, int y, int left, int right)
Sets Spanerator to return line segments in Region on scan line.
### Parameters
### Return Value
Region iterator
### Example
### See Also
SkRegion Iterator Cliperator
---
## next
bool next(int* left, int* right)
Advances iterator to next span intersecting Region within line segment provided
in constructor. Returns true if interval was found.
### Parameters
left |
pointer to span start; may be nullptr |
right |
pointer to span end; may be nullptr |
### Return Value
true if interval was found
### Example
#### Example Output
~~~~
empty region: result=false
after set rect: result=true left=2 right=3
~~~~
### See Also
done
---
## SkRegion
SkRegion()
Constructs an empty Region. Region is set to empty bounds
at (0, 0) with zero width and height.
### Return Value
empty Region
### Example
#### Example Output
~~~~
region bounds: {0, 0, 0, 0}
~~~~
### See Also
setEmpty
---
## SkRegion
SkRegion(const SkRegion& region)
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.
### Parameters
### Return Value
copy of Region
### Example
#### Example Output
~~~~
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}
~~~~
### See Also
setRegion operator=(const SkRegion& region)
---
## SkRegion
explicit SkRegion(const SkIRect& rect)
Constructs a rectangular Region matching the bounds of rect.
### Parameters
### Return Value
rectangular Region
### Example
### See Also
setRect[2] setRegion
---
## ~SkRegion
~SkRegion()
Releases ownership of any shared data and deletes data if Region is sole owner.
### Example
#### Example Output
~~~~
region2 bounds: {1,2,3,4}
~~~~
### See Also
SkRegion() SkRegion(const SkRegion& region) SkRegion(const SkIRect& rect) operator=(const SkRegion& region)
---
## operator=
SkRegion& 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.
### Parameters
### Return Value
Region to copy by value
### Example
#### Example Output
~~~~
region1 bounds: {1,2,3,4}
region2 bounds: {1,2,3,4}
~~~~
### See Also
set swap SkRegion(const SkRegion& region)
---
## operator==
bool operator==(const SkRegion& other) _const
Compares Region and other; returns true if they enclose exactly
the same area.
### Parameters
### Return Value
true if Region pair are equivalent
### Example
#### Example Output
~~~~
empty one == two
set rect one != two
set empty one == two
~~~~
### See Also
operator!=(const SkRegion& other) const operator=(const SkRegion& region)
---
## operator!=
bool operator!=(const SkRegion& other) _const
Compares Region and other; returns true if they do not enclose the same area.
### Parameters
### Return Value
true if Region pair are not equivalent
### Example
#### Example Output
~~~~
empty one == two
set rect one != two
union rect one == two
~~~~
### See Also
operator==(const SkRegion& other) const operator=(const SkRegion& region)
---
## set
bool set(const SkRegion& src)
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.
### Parameters
### Return Value
copy of src
### Example
#### Example Output
~~~~
region1 bounds: {1,2,3,4}
region2 bounds: {1,2,3,4}
~~~~
### See Also
operator=(const SkRegion& region) swap SkRegion(const SkRegion& region)
---
## swap
void swap(SkRegion& other)
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.
### Parameters
### Example
#### Example Output
~~~~
region1 bounds: {0,0,0,0}
region2 bounds: {1,2,3,4}
~~~~
### See Also
operator=(const SkRegion& region) set SkRegion(const SkRegion& region)
---
## isEmpty
bool isEmpty() const
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.
### Return Value
true if bounds has no width or height
### Example
#### Example Output
~~~~
initial: region is empty
set rect: region is not empty
set empty: region is empty
~~~~
### See Also
isRect isComplex operator==(const SkRegion& other) const
---
## isRect
bool isRect() const
Returns true if Region is one IRect with positive dimensions.
### Return Value
true if Region contains one IRect
### Example
#### Example Output
~~~~
initial: region is not rect
set rect: region is rect
set empty: region is not rect
~~~~
### See Also
isEmpty isComplex
---
## isComplex
bool isComplex() const
Returns true if Region is described by more than one rectangle.
### Return Value
true if Region contains more than one IRect
### Example
#### Example Output
~~~~
initial: region is not complex
set rect: region is not complex
op rect: region is complex
~~~~
### See Also
isEmpty isRect
---
## getBounds
const SkIRect& getBounds() const
Returns minimum and maximum axes values of IRect array.
Returns (0, 0, 0, 0) if Region is empty.
### Return Value
combined bounds of all IRect elements
### Example
#### Example Output
~~~~
bounds: {1,2,4,5}
~~~~
### See Also
isEmpty isRect
---
## computeRegionComplexity
int computeRegionComplexity() const
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.
### Return Value
relative complexity
### Example
#### Example Output
~~~~
initial: region complexity 0
set rect: region complexity 1
op rect: region complexity 3
~~~~
### See Also
isRect isComplex
---
## getBoundaryPath
bool getBoundaryPath(SkPath* path) const
Appends outline of Region to path.
Returns true if Region is not empty; otherwise, returns false, and leaves path
unmodified.
### Parameters
### Return Value
true if path changed
### Example
### See Also
isEmpty isComplex
---
## setEmpty
bool setEmpty()
Constructs an empty Region. Region is set to empty bounds
at (0, 0) with zero width and height. Always returns false.
### Return Value
false
### Example
#### Example Output
~~~~
region bounds: {1,2,3,4}
after region set empty:
region bounds: {0,0,0,0}
~~~~
### See Also
SkRegion()
---
## setRect
bool setRect(const SkIRect& rect)
Constructs a rectangular Region matching the bounds of rect.
If rect is empty, constructs empty and returns false.
### Parameters
### Return Value
true if rect is not empty
### Example
#### Example Output
~~~~
region is not empty
region is empty
setEmpty: false
~~~~
### See Also
SkRegion(const SkIRect& rect)
---
bool setRect(int32_t left, int32_t top, int32_t right, int32_t bottom)
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.
### Parameters
left |
edge of bounds on x-axis |
top |
edge of bounds on y-axis |
right |
edge of bounds on x-axis |
bottom |
edge of bounds on y-axis |
### Return Value
rectangular Region
### Example
#### Example Output
~~~~
set to: 1,2,3,4: success:true {1,2,3,4}
set to: 3,2,1,4: success:false {0,0,0,0}
~~~~
### See Also
SkRegion(const SkIRect& rect)
---
## setRects
bool setRects(const SkIRect rects[], int count)
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.
### Parameters
### Return Value
true if constructed Region is not empty
### Example
### See Also
setRect[2] op[2][3][4][5][6]
---
## setRegion
bool setRegion(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.
### Parameters
### Return Value
Region to copy by value
### Example
#### Example Output
~~~~
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}
~~~~
### See Also
SkRegion(const SkRegion& region)
---
## setPath
bool setPath(const SkPath& path, const SkRegion& clip)
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.
### Parameters
### Return Value
true if constructed Region is not empty
### Example
### See Also
setRects op[2][3][4][5][6]
---
## intersects
bool intersects(const SkIRect& rect) const
Returns true if Region intersects rect.
Returns false if either rect or Region is empty, or do not intersect.
### Parameters
### Return Value
true if rect and Region have area in common
### Example
### See Also
contains[2][3] SkRect::intersects[2]
---
bool intersects(const SkRegion& other) const
Returns true if Region intersects other.
Returns false if either other or Region is empty, or do not intersect.
### Parameters
### Return Value
true if other and Region have area in common
### Example
### See Also
contains[2][3] SkRect::intersects[2]
---
## contains
bool contains(int32_t x, int32_t y) const
Returns true if IPoint (x, y) is inside Region.
Returns false if Region is empty.
### Parameters
### Return Value
true if (x, y) is inside Region
### Example
### See Also
intersects[2] SkRect::contains[2][3]
---
bool contains(const SkIRect& other) const
Returns true if other is completely inside Region.
Returns false if Region or other is empty.
### Parameters
### Return Value
true if other is inside Region
### Example
### See Also
intersects[2] SkRect::contains[2][3]
---
bool contains(const SkRegion& other) const
Returns true if other is completely inside Region.
Returns false if Region or other is empty.
### Parameters
### Return Value
true if other is inside Region
### Example
### See Also
intersects[2] SkRect::contains[2][3]
---
## quickContains
bool quickContains(const SkIRect& r) const
Returns true if Region is a single rectangle and contains r.
May return false even though Region contains r.
### Parameters
### Return Value
true quickly if r points are equal or inside
### Example
#### Example Output
~~~~
quickContains 1: true
quickContains 2: true
quickContains 3: false
~~~~
### See Also
contains[2][3] quickReject[2] intersects[2]
---
bool quickContains(int32_t left, int32_t top, int32_t right, int32_t bottom) const
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).
### Parameters
left |
edge of bounds on x-axis |
top |
edge of bounds on y-axis |
right |
edge of bounds on x-axis |
bottom |
edge of bounds on y-axis |
### Return Value
true quickly if IRect are equal or inside
### Example
#### Example Output
~~~~
quickContains 1: true
quickContains 2: true
quickContains 3: false
~~~~
### See Also
contains[2][3] quickReject[2] intersects[2]
---
## quickReject
bool quickReject(const SkIRect& rect) const
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.
### Parameters
### Return Value
true if rect does not intersect
### Example
#### Example Output
~~~~
quickReject 1: true
quickReject 2: true
quickReject 3: false
~~~~
### See Also
quickContains[2] contains[2][3] intersects[2]
---
bool quickReject(const SkRegion& rgn) const
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.
### Parameters
### Return Value
true if rgn does not intersect
### Example
#### Example Output
~~~~
quickReject 1: true
quickReject 2: true
quickReject 3: false
~~~~
### See Also
quickContains[2] contains[2][3] intersects[2]
---
## translate
void translate(int dx, int dy)
Offsets Region by IVector (dx, dy). Has no effect if Region is empty.
### Parameters
dx |
x-axis offset |
dy |
y-axis offset |
### Example
### See Also
SkCanvas::translate SkIRect::offset[2] SkPath::offset[2]
---
void translate(int dx, int dy, SkRegion* dst) const
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.
### Parameters
dx |
x-axis offset |
dy |
y-axis offset |
dst |
translated result |
### Example
### See Also
SkCanvas::translate SkIRect::offset[2] SkPath::offset[2]
---
## Enum SkRegion::Op
enum Op {
kDifference Op,
kIntersect Op,
kUnion Op,
kXOR Op,
kReverseDifference Op,
kReplace Op,
kLastOp = kReplace Op,
};
The logical operations that can be performed when combining two Regions.
### Constants
### Example
### See Also
SkPathOp
### Constants
Const |
Value |
Description |
SkRegion::kOpCnt |
6 |
May be used to verify that Op is a legal value. |
## op
bool op(const SkIRect& rect, Op op)
Replaces Region with the result of Region op rect.
Returns true if replaced Region is not empty.
### Parameters
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(int left, int top, int right, int bottom, Op op)
Replaces Region with the result of Region op IRect (left, top, right, bottom).
Returns true if replaced Region is not empty.
### Parameters
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkRegion& rgn, Op op)
Replaces Region with the result of Region op rgn.
Returns true if replaced Region is not empty.
### Parameters
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkIRect& rect, const SkRegion& rgn, Op op)
Replaces Region with the result of rect op rgn.
Returns true if replaced Region is not empty.
### Parameters
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkRegion& rgn, const SkIRect& rect, Op op)
Replaces Region with the result of rgn op rect.
Returns true if replaced Region is not empty.
### Parameters
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkRegion& rgna, const SkRegion& rgnb, Op op)
Replaces Region with the result of rgna op rgnb.
Returns true if replaced Region is not empty.
### Parameters
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
## toString
char* toString()
### Return Value
string representation of Region
---
## writeToMemory
size_t writeToMemory(void* buffer) const
Writes Region to buffer, and returns number of bytes written.
If buffer is nullptr, returns number number of bytes that would be written.
### Parameters
buffer |
storage for binary data |
### Return Value
size of Region
### Example
### See Also
readFromMemory
---
## readFromMemory
size_t readFromMemory(const void* buffer, size_t length)
Constructs Region from buffer of size length. Returns bytes read.
Returned value will be multiple of four or zero if length was too small.
### Parameters
### Return Value
bytes read
### Example
### See Also
writeToMemory
---