SkRegion_Reference.md 80 KB

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

region SkRegion to iterate

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

region SkRegion to iterate

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

region SkRegion to iterate
clip bounds of iteration

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

region SkRegion to iterate
y horizontal line to intersect
left bounds of iteration
right bounds of iteration

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

region SkRegion to copy by value

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

rect bounds of constructed SkRegion

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

region SkRegion to copy by value

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

other SkRegion to compare

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

other SkRegion to compare

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

src SkRegion to copy

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

other operator=(const SkRegion& region) set

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

path SkPath to append to

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

rect bounds of constructed SkRegion

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

rects array of SkIRect
count array size

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

region SkRegion to copy by value

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

path SkPath providing outline
clip SkRegion containing path

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

rect SkIRect to intersect

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

other SkRegion to intersect

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

x test SkIPoint x-coordinate
y test SkIPoint y-coordinate

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

other SkIRect to contain

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

other SkRegion to contain

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

r SkIRect to contain

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

rect SkIRect to intersect

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

rgn SkRegion to intersect

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

Const Value Description
SkRegion::kDifference_Op 0 Subtracts operand Region from target Region.
SkRegion::kIntersect_Op 1 Intersects operand Region and target Region.
SkRegion::kUnion_Op 2 Unions operand Region and target Region.
SkRegion::kXOR_Op 3 Replaces target Region with area exclusive to both Regions.
SkRegion::kReverseDifference_Op 4 Subtracts target Region from operand Region.
SkRegion::kReplace_Op 5 Replaces target Region with operand Region.
SkRegion::kLastOp 5 last operator

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

rect SkIRect operand
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(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

rgn SkRegion operand
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 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

rect SkIRect operand
rgn SkRegion operand
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, const SkIRect& rect, Op op)

Replaces SkRegion with the result of rgn op rect. Returns true if replaced SkRegion is not empty.

Parameters

rgn SkRegion operand
rect SkIRect operand
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& rgna, const SkRegion& rgnb, Op op)

Replaces SkRegion with the result of rgna op rgnb. Returns true if replaced SkRegion is not empty.

Parameters

rgna SkRegion operand
rgnb SkRegion operand
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


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

buffer storage for binary data

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

buffer storage for binary data
length size of buffer

Return Value

bytes read

Example

See Also

writeToMemory