SkRegion Reference
===
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();
SkRegion(const SkRegion& region);
explicit SkRegion(const SkIRect& rect);
~SkRegion();
SkRegion& operator=(const SkRegion& region);
bool operator==(const SkRegion& other) const;
bool operator!=(const SkRegion& other) const;
bool set(const SkRegion& src);
void swap(SkRegion& other);
bool isEmpty() const;
bool isRect() const;
bool isComplex() const;
const SkIRect& getBounds() const;
int computeRegionComplexity() const;
bool getBoundaryPath(SkPath* path) const;
bool setEmpty();
bool setRect(const SkIRect& rect);
bool setRect(int32_t left, int32_t top, int32_t right, int32_t bottom);
bool setRects(const SkIRect rects[], int count);
bool setRegion(const SkRegion& region);
bool setPath(const SkPath& path, const SkRegion& clip);
bool intersects(const SkIRect& rect) const;
bool intersects(const SkRegion& other) const;
bool contains(int32_t x, int32_t y) const;
bool contains(const SkIRect& other) const;
bool contains(const SkRegion& other) const;
bool quickContains(const SkIRect& r) const;
bool quickContains(int32_t left, int32_t top, int32_t right,
int32_t bottom) const;
bool quickReject(const SkIRect& rect) const;
bool quickReject(const SkRegion& rgn) const;
void translate(int dx, int dy);
void translate(int dx, int dy, SkRegion* dst) const;
enum Op {
kDifference_Op,
kIntersect_Op,
kUnion_Op,
kXOR_Op,
kReverseDifference_Op,
kReplace_Op,
kLastOp = kReplace_Op,
};
static const int kOpCnt = kLastOp + 1
bool op(const SkIRect& rect, Op op);
bool op(int left, int top, int right, int bottom, Op op);
bool op(const SkRegion& rgn, Op op);
bool op(const SkIRect& rect, const SkRegion& rgn, Op op);
bool op(const SkRegion& rgn, const SkIRect& rect, Op op);
bool op(const SkRegion& rgna, const SkRegion& rgnb, Op op);
size_t writeToMemory(void* buffer) const;
size_t readFromMemory(const void* buffer, size_t length);
};
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.
---
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()
Initializes SkRegion::Iterator with an empty SkRegion. done() on SkRegion::Iterator
returns true.
Call reset() to initialized SkRegion::Iterator at a later time.
### Return Value
empty SkRegion iterator
### Example
#### Example Output
~~~~
rect={1,2,3,4}
~~~~
### See Also
reset SkRegion
---
Iterator(const SkRegion& region)
Sets SkRegion::Iterator to return elements of SkIRect array in region.
### Parameters
### Return Value
SkRegion iterator
### Example
#### Example Output
~~~~
rect={1,2,3,4}
~~~~
### See Also
reset SkRegion Cliperator Spanerator
---
bool rewind()
SkPoint SkRegion::Iterator to start of SkRegion.
Returns true if SkRegion was set; otherwise, returns false.
### Return Value
true if SkRegion 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
---
void reset(const SkRegion& region)
Resets iterator, using the new SkRegion.
### Parameters
### Example
#### Example Output
~~~~
empty region: done=true
after set rect: done=true
after reset: done=false
~~~~
### See Also
rewind
---
bool done()const
Returns true if SkRegion::Iterator is pointing to final SkIRect in SkRegion.
### Return Value
true if data parsing is complete
### Example
#### Example Output
~~~~
done=true
done=false
~~~~
### See Also
next rect
---
void next()
Advances SkRegion::Iterator to next SkIRect in SkRegion if it is not done.
### Example
#### Example Output
~~~~
rect={1,2,3,4}
rect={5,6,7,8}
~~~~
### See Also
done rect
---
const SkIRect& rect()const
Returns SkIRect element in SkRegion. Does not return predictable results if SkRegion
is empty.
### Return Value
part of SkRegion as SkIRect
### Example
#### Example Output
~~~~
#Volatile
rect={0,0,0,0}
rect={1,2,3,4}
~~~~
### See Also
next done
---
const SkRegion* rgn()const
Returns SkRegion if set; otherwise, returns nullptr.
### Return Value
iterated SkRegion
### Example
### See Also
Iterator reset
---
class 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(const SkRegion& region, const SkIRect& clip)
Sets SkRegion::Cliperator to return elements of SkIRect array in SkRegion within clip.
### Parameters
### Return Value
SkRegion iterator
### Example
#### Example Output
~~~~
rect={1,2,2,3}
~~~~
### See Also
SkRegion Iterator Spanerator
---
bool done()
Returns true if SkRegion::Cliperator is pointing to final SkIRect in SkRegion.
### Return Value
true if data parsing is complete
### Example
#### Example Output
~~~~
empty region done=true
after add rect done=false
~~~~
### See Also
next rect
---
void next()
Advances iterator to next SkIRect in SkRegion contained by clip.
### Example
#### Example Output
~~~~
rect={1,3,3,4}
rect={5,6,7,7}
~~~~
### See Also
done
---
const SkIRect& rect()const
Returns SkIRect element in SkRegion, intersected with clip passed to
SkRegion::Cliperator constructor. Does not return predictable results if SkRegion
is empty.
### Return Value
part of SkRegion inside clip as SkIRect
### Example
#### Example Output
~~~~
#Volatile
empty region rect={1094713344,1065353216,0,-1}
after set rect rect={1,2,3,3}
~~~~
### See Also
next done
---
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(const SkRegion& region, int y, int left, int right)
Sets SkRegion::Spanerator to return line segments in SkRegion on scan line.
### Parameters
### Return Value
SkRegion iterator
### Example
### See Also
SkRegion Iterator Cliperator
---
bool next(int* left, int* right)
Advances iterator to next span intersecting SkRegion 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()
Constructs an empty SkRegion. SkRegion is set to empty bounds
at (0, 0) with zero width and height.
### Return Value
empty SkRegion
### Example
#### Example Output
~~~~
region bounds: {0, 0, 0, 0}
~~~~
### See Also
setEmpty
---
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 SkRect array is
copied when modified.
Creating a SkRegion copy is very efficient and never allocates memory.
SkRegion are always copied by value from the interface; the underlying shared
pointers are not exposed.
### Parameters
### Return Value
copy of SkRegion
### 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)
---
explicit SkRegion(const SkIRect& rect)
Constructs a rectangular SkRegion matching the bounds of rect.
### Parameters
### Return Value
rectangular SkRegion
### Example
### See Also
setRect setRegion
---
~SkRegion()
Releases ownership of any shared data and deletes data if SkRegion is sole owner.
### Example
delete calls
Region destructor, but copy of original in region2 is unaffected.
#### Example Output
~~~~
region2 bounds: {1,2,3,4}
~~~~
### See Also
SkRegion() SkRegion(const SkRegion& region) SkRegion(const SkIRect& rect) operator=(const SkRegion& region)
---
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 SkRect array is
copied when modified.
Creating a SkRegion copy is very efficient and never allocates memory.
SkRegion are always copied by value from the interface; the underlying shared
pointers are not exposed.
### Parameters
### Return Value
SkRegion 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)
---
bool operator==(const SkRegion& other)const
Compares SkRegion and other; returns true if they enclose exactly
the same area.
### Parameters
### Return Value
true if SkRegion 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)
---
bool operator!=(const SkRegion& other)const
Compares SkRegion and other; returns true if they do not enclose the same area.
### Parameters
### Return Value
true if SkRegion 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)
---
bool set(const SkRegion& src)
Sets SkRegion to src, and returns true if src bounds is not empty.
This makes SkRegion and src identical by value. Internally,
SkRegion and src share pointer values. The underlying SkRect array is
copied when modified.
Creating a SkRegion copy is very efficient and never allocates memory.
SkRegion 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)
---
void swap(SkRegion& other)
Exchanges SkIRect array of SkRegion 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).
SkPath 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)
---
bool isEmpty()const
Returns true if SkRegion is empty.
Empty SkRegion has bounds width or height less than or equal to zero.
SkRegion() constructs empty SkRegion; setEmpty()
and setRect() with dimensionless data make SkRegion 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
---
bool isRect()const
Returns true if SkRegion is one SkIRect with positive dimensions.
### Return Value
true if SkRegion contains one SkIRect
### Example
#### Example Output
~~~~
initial: region is not rect
set rect: region is rect
set empty: region is not rect
~~~~
### See Also
isEmpty isComplex
---
bool isComplex()const
Returns true if SkRegion is described by more than one rectangle.
### Return Value
true if SkRegion contains more than one SkIRect
### Example
#### Example Output
~~~~
initial: region is not complex
set rect: region is not complex
op rect: region is complex
~~~~
### See Also
isEmpty isRect
---
const SkIRect& getBounds()const
Returns minimum and maximum axes values of SkIRect array.
Returns (0, 0, 0, 0) if SkRegion is empty.
### Return Value
combined bounds of all SkIRect elements
### Example
#### Example Output
~~~~
bounds: {1,2,4,5}
~~~~
### See Also
isEmpty isRect
---
int computeRegionComplexity()const
Returns a value that increases with the number of
elements in SkRegion. Returns zero if SkRegion is empty.
Returns one if SkRegion equals SkIRect; otherwise, returns
value greater than one indicating that SkRegion is complex.
Call to compare SkRegion 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
---
bool getBoundaryPath(SkPath* path)const
Appends outline of SkRegion to path.
Returns true if SkRegion is not empty; otherwise, returns false, and leaves path
unmodified.
### Parameters
### Return Value
true if path changed
### Example
### See Also
isEmpty isComplex
---
bool setEmpty()
Constructs an empty SkRegion. SkRegion 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()
---
bool setRect(const SkIRect& rect)
Constructs a rectangular SkRegion 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 SkRegion with bounds (left, top, right, bottom).
Returns true if left is less than right and top is less than bottom; otherwise,
constructs empty SkRegion 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 SkRegion
### 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)
---
bool setRects(const SkIRect rects[], int count)
Constructs SkRegion as the union of SkIRect in rects array. If count is
zero, constructs empty SkRegion. Returns false if constructed SkRegion is empty.
May be faster than repeated calls to op().
### Parameters
### Return Value
true if constructed SkRegion is not empty
### Example
### See Also
setRect op
---
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 SkRect array is
copied when modified.
Creating a SkRegion copy is very efficient and never allocates memory.
SkRegion are always copied by value from the interface; the underlying shared
pointers are not exposed.
### Parameters
### Return Value
SkRegion 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)
---
bool setPath(const SkPath& path, const SkRegion& clip)
Constructs SkRegion to match outline of path within clip.
Returns false if constructed SkRegion is empty.
Constructed SkRegion draws the same pixels as path through clip when
anti-aliasing is disabled.
### Parameters
### Return Value
true if constructed SkRegion is not empty
### Example
### See Also
setRects op
---
bool intersects(const SkIRect& rect)const
Returns true if SkRegion intersects rect.
Returns false if either rect or SkRegion is empty, or do not intersect.
### Parameters
### Return Value
true if rect and SkRegion have area in common
### Example
### See Also
contains SkRect::intersects
---
bool intersects(const SkRegion& other)const
Returns true if SkRegion intersects other.
Returns false if either other or SkRegion is empty, or do not intersect.
### Parameters
### Return Value
true if other and SkRegion have area in common
### Example
### See Also
contains SkRect::intersects
---
bool contains(int32_t x, int32_t y)const
Returns true if SkIPoint (x, y) is inside SkRegion.
Returns false if SkRegion is empty.
### Parameters
### Return Value
true if (x, y) is inside SkRegion
### Example
### See Also
intersects SkRect::contains
---
bool contains(const SkIRect& other)const
Returns true if other is completely inside SkRegion.
Returns false if SkRegion or other is empty.
### Parameters
### Return Value
true if other is inside SkRegion
### Example
### See Also
intersects SkRect::contains
---
bool contains(const SkRegion& other)const
Returns true if other is completely inside SkRegion.
Returns false if SkRegion or other is empty.
### Parameters
### Return Value
true if other is inside SkRegion
### Example
### See Also
intersects SkRect::contains
---
bool quickContains(const SkIRect& r)const
Returns true if SkRegion is a single rectangle and contains r.
May return false even though SkRegion 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 quickReject intersects
---
bool quickContains(int32_t left, int32_t top, int32_t right, int32_t bottom)const
Returns true if SkRegion is a single rectangle and contains SkIRect
(left, top, right, bottom).
Returns false if SkRegion is empty or SkIRect (left, top, right, bottom) is empty.
May return false even though SkRegion 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 SkIRect are equal or inside
### Example
#### Example Output
~~~~
quickContains 1: true
quickContains 2: true
quickContains 3: false
~~~~
### See Also
contains quickReject intersects
---
bool quickReject(const SkIRect& rect)const
Returns true if SkRegion does not intersect rect.
Returns true if rect is empty or SkRegion is empty.
May return false even though SkRegion 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 contains intersects
---
bool quickReject(const SkRegion& rgn)const
Returns true if SkRegion does not intersect rgn.
Returns true if rgn is empty or SkRegion is empty.
May return false even though SkRegion 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 contains intersects
---
void translate(int dx, int dy)
Offsets SkRegion by ivector (dx, dy). Has no effect if SkRegion is empty.
### Parameters
dx |
x-axis offset |
dy |
y-axis offset |
### Example
### See Also
SkCanvas::translate SkIRect::offset SkPath::offset
---
void translate(int dx, int dy, SkRegion* dst)const
Offsets SkRegion by ivector (dx, dy), writing result to dst. SkRegion may be passed
as dst parameter, translating SkRegion in place. Has no effect if dst is nullptr.
If SkRegion 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 SkPath::offset
---
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. |
---
bool op(const SkIRect& rect, Op op)
Replaces SkRegion with the result of SkRegion op rect.
Returns true if replaced SkRegion is not empty.
### Parameters
kDifference_Op, kIntersect_Op, kUnion_Op, kXOR_Op, kReverseDifference_Op,
kReplace_Op
### 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 SkRegion with the result of SkRegion op SkIRect (left, top, right, bottom).
Returns true if replaced SkRegion is not empty.
### 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 |
op |
operator, one of: |
kDifference_Op, kIntersect_Op, kUnion_Op, kXOR_Op, kReverseDifference_Op,
kReplace_Op
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkRegion& rgn, Op op)
Replaces SkRegion with the result of SkRegion op rgn.
Returns true if replaced SkRegion is not empty.
### Parameters
kDifference_Op, kIntersect_Op, kUnion_Op, kXOR_Op, kReverseDifference_Op,
kReplace_Op
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkIRect& rect, const SkRegion& rgn, Op op)
Replaces SkRegion with the result of rect op rgn.
Returns true if replaced SkRegion is not empty.
### Parameters
kDifference_Op, kIntersect_Op, kUnion_Op, kXOR_Op, kReverseDifference_Op,
kReplace_Op
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkRegion& rgn, const SkIRect& rect, Op op)
Replaces SkRegion with the result of rgn op rect.
Returns true if replaced SkRegion is not empty.
### Parameters
kDifference_Op, kIntersect_Op, kUnion_Op, kXOR_Op, kReverseDifference_Op,
kReplace_Op
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
bool op(const SkRegion& rgna, const SkRegion& rgnb, Op op)
Replaces SkRegion with the result of rgna op rgnb.
Returns true if replaced SkRegion is not empty.
### Parameters
kDifference_Op, kIntersect_Op, kUnion_Op, kXOR_Op, kReverseDifference_Op,
kReplace_Op
### Return Value
false if result is empty
### Example
### See Also
setRects Op
---
size_t writeToMemory(void* buffer)const
Writes SkRegion to buffer, and returns number of bytes written.
If buffer is nullptr, returns number number of bytes that would be written.
### Parameters
### Return Value
size of SkRegion
### Example
### See Also
readFromMemory
---
size_t readFromMemory(const void* buffer, size_t length)
Constructs SkRegion 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