Region

class Region

Region describes the set of pixels used to clip Canvas.

Region is compact, efficiently storing a single integer rectangle, or a run length encoded array of rectangles. Region may reduce the current Canvas clip, or may be drawn as one or more integer rectangles. Region iterator returns the scan lines or rectangles contained by it, optionally intersecting a bounding rectangle.

Region supports a few operators:

regionA == regionB  # Equality
regionA != regionB  # Inequality

regionA - regionB   # Difference
regionA & regionB   # Intersect
regionA | regionB   # Union
regionA ^ regionB   # XOR

regionA -= regionB  # In-place Difference
regionA &= regionB  # In-place Intersect
regionA |= regionB  # In-place Union
regionA ^= regionB  # In-place XOR

Classes

`Cliperator`	Returns the sequence of rectangles, sorted along y-axis, then x-axis, that make up `Region` intersected with the specified clip rectangle.
`Iterator`	Returns sequence of rectangles, sorted along y-axis, then x-axis, that make up `Region`.
`Op`	Members:
`Spanerator`	Returns the line segment ends within `Region` that intersect a horizontal line.

Methods

`__init__`	Overloaded function.
`cliperator`	Creates `Cliperator` to return elements of `IRect` array in `Region` within clip.
`computeRegionComplexity`	Returns a value that increases with the number of elements in `Region`.
`contains`	Overloaded function.
`getBoundaryPath`	Appends outline of `Region` to path.
`getBounds`	Returns minimum and maximum axes values of `IRect` array.
`intersects`	Overloaded function.
`isComplex`	Returns true if `Region` is described by more than one rectangle.
`isEmpty`	Returns true if `Region` is empty.
`isRect`	Returns true if `Region` is one `IRect` with positive dimensions.
`iterator`	Creates `Iterator` to return elements of `IRect` array in region.
`op`	Overloaded function.
`quickContains`	Returns true if `Region` is a single rectangle and contains r.
`quickReject`	Overloaded function.
`readFromMemory`	Constructs `Region` from buffer of size length.
`set`	Sets `Region` to src, and returns true if src bounds is not empty.
`setEmpty`	Constructs an empty `Region`.
`setPath`	Constructs `Region` to match outline of path within clip.
`setRect`	Constructs a rectangular `Region` matching the bounds of rect.
`setRects`	Constructs `Region` as the union of `IRect` in rects array.
`setRegion`	Constructs a copy of an existing region.
`spanerator`	Creates `Region.Spanerator` to return line segments in `Region` on scan line.
`swap`	Exchanges `IRect` array of `Region` and other.
`translate`	Offsets `Region` by ivector (dx, dy).
`writeToMemory`	Writes `Region` to `Data`.

Attributes

`kDifference_Op`
`kIntersect_Op`
`kLastOp`
`kOpCnt`
`kReplace_Op`
`kReverseDifference_Op`
`kUnion_Op`
`kXOR_Op`

Methods

Region.__init__(*args, **kwargs)

Overloaded function.

__init__(self: skia.Region) -> None

Constructs an empty Region.

Region is set to empty bounds at (0, 0) with zero width and height.
__init__(self: skia.Region, region: skia.Region) -> None

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. Region are always copied by value from the interface; the underlying shared pointers are not exposed.

region:

Region to copy by value
__init__(self: skia.Region, rect: skia.IRect) -> None

Constructs a rectangular Region matching the bounds of rect.

rect:

bounds of constructed Region

Region.cliperator(self: skia.Region, clip: skia.IRect) → skia.Region.Cliperator

Creates Cliperator to return elements of IRect array in Region within clip.

Example:

for rect in region.cliperator(skia.IRect(100, 100)):
    pass

Parameters:: clip (skia.IRect) – bounds of iteration

Region.computeRegionComplexity(self: skia.Region) → int

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 Region for relative complexity.

Returns:: relative complexity

Region.contains(*args, **kwargs)

Overloaded function.

contains(self: skia.Region, x: int, y: int) -> bool

Returns true if IPoint (x, y) is inside Region.

Returns false if Region is empty.

x:

test IPoint x-coordinate

y:

test IPoint y-coordinate

return:

true if (x, y) is inside Region
contains(self: skia.Region, other: skia.IRect) -> bool

Returns true if other is completely inside Region.

Returns false if Region or other is empty.

other:

IRect to contain

return:

true if other is inside Region
contains(self: skia.Region, other: skia.Region) -> bool

Returns true if other is completely inside Region.

Returns false if Region or other is empty.

other:

Region to contain

return:

true if other is inside Region

Region.getBoundaryPath(self: skia.Region, path: SkPath) → bool

Appends outline of Region to path.

Returns true if Region is not empty; otherwise, returns false, and leaves path unmodified.

Parameters:: path (skia.Path) – Path to append to
Returns:: true if path changed

Region.getBounds(self: skia.Region) → skia.IRect

Returns minimum and maximum axes values of IRect array.

Returns (0, 0, 0, 0) if Region is empty.

Returns:: combined bounds of all IRect elements

Region.intersects(*args, **kwargs)

Overloaded function.

intersects(self: skia.Region, rect: skia.IRect) -> bool

Returns true if Region intersects rect.

Returns false if either rect or Region is empty, or do not intersect.

rect:

IRect to intersect

return:

true if rect and Region have area in common
intersects(self: skia.Region, other: skia.Region) -> bool

Returns true if Region intersects other.

Returns false if either other or Region is empty, or do not intersect.

other:

Region to intersect

return:

true if other and Region have area in common

Region.isComplex(self: skia.Region) → bool

Returns true if Region is described by more than one rectangle.

Returns:: true if Region contains more than one IRect

Region.isEmpty(self: skia.Region) → bool

Returns true if Region is empty.

Empty Region has bounds width or height less than or equal to zero. __init__() constructs empty Region; setEmpty() and setRect() with dimensionless data make Region empty.

Returns:: true if bounds has no width or height

Region.isRect(self: skia.Region) → bool

Returns true if Region is one IRect with positive dimensions.

Returns:: true if Region contains one IRect

Region.iterator(self: skia.Region) → skia.Region.Iterator

Creates Iterator to return elements of IRect array in region.

Example:

for rect in region.iterator():
    pass

Region.op(*args, **kwargs)

Overloaded function.

op(self: skia.Region, rect: skia.IRect, op: skia.Region.Op) -> bool

Replaces Region with the result of Region op rect.

Returns true if replaced Region is not empty.

rect:

IRect operand

return:

false if result is empty
op(self: skia.Region, region: skia.Region, op: skia.Region.Op) -> bool

Replaces Region with the result of Region op region.

Returns true if replaced Region is not empty.

region:

Region operand

return:

false if result is empty
op(self: skia.Region, rect: skia.IRect, region: skia.Region, op: skia.Region.Op) -> bool

Replaces Region with the result of rect op region.

Returns true if replaced Region is not empty.

rect:

IRect operand

region:

Region operand

return:

false if result is empty
op(self: skia.Region, region: skia.Region, rect: skia.IRect, op: skia.Region.Op) -> bool

Replaces Region with the result of region op rect.

Returns true if replaced Region is not empty.

region:

Region operand

rect:

IRect operand

return:

false if result is empty
op(self: skia.Region, regionA: skia.Region, regionB: skia.Region, op: skia.Region.Op) -> bool

Replaces Region with the result of regionA op regionB.

Returns true if replaced Region is not empty.

regionA:

Region operand

regionB:

Region operand

return:

false if result is empty

Region.quickContains(self: skia.Region, r: skia.IRect) → bool

Returns true if Region is a single rectangle and contains r.

May return false even though Region contains r.

Parameters:: r (skia.IRect) – IRect to contain
Returns:: true quickly if r points are equal or inside

Region.quickReject(*args, **kwargs)

Overloaded function.

quickReject(self: skia.Region, rect: skia.IRect) -> bool

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.

rect:

IRect to intersect

return:

true if rect does not intersect
quickReject(self: skia.Region, region: skia.Region) -> bool

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.

rgn:

Region to intersect

return:

true if rgn does not intersect

Region.readFromMemory(self: skia.Region, data: SkData) → int

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:: data (skia.Data) – binary data
Returns:: bytes read

Region.set(self: skia.Region, src: skia.Region) → bool

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. Region are always copied by value from the interface; the underlying shared pointers are not exposed.

Parameters:: src (skia.Region) – Region to copy
Returns:: copy of src

Region.setEmpty(self: skia.Region) → bool

Constructs an empty Region.

Region is set to empty bounds at (0, 0) with zero width and height. Always returns false.

Returns:: false

Region.setPath(self: skia.Region, path: SkPath, clip: skia.Region) → bool

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:

path (skia.Path) – Path providing outline
clip (skia.Region) – Region containing path

Returns:

true if constructed Region is not empty

Region.setRect(self: skia.Region, rect: skia.IRect) → bool

Constructs a rectangular Region matching the bounds of rect.

If rect is empty, constructs empty and returns false.

Parameters:: rect (skia.Rect) – bounds of constructed Region
Returns:: true if rect is not empty

Region.setRects(self: skia.Region, rects: list[skia.IRect]) → bool

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:: rects (List[skia.IRect]) – array of IRect
Returns:: true if constructed Region is not empty

Region.setRegion(self: skia.Region, region: skia.Region) → bool

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. Region are always copied by value from the interface; the underlying shared pointers are not exposed.

Parameters:: region (skia.Region) – Region to copy by value
Returns:: Region to copy by value

Region.spanerator(self: skia.Region, y: int, left: int, right: int) → skia.Region.Spanerator

Creates Region.Spanerator to return line segments in Region on scan line.

Example:

for left, right in region.spanerator(5, 0, 100):
    pass

Parameters:

y (int) – horizontal line to intersect
left (int) – bounds of iteration
right (int) – bounds of iteration

Region.swap(self: skia.Region, other: skia.Region) → None

Exchanges IRect array of Region and other.

swap() internally exchanges pointers, so it is lightweight and does not allocate memory.

Path do not copy their content on assignment until they are written to, making assignment as efficient as swap().

Parameters:: other (skia.Region) – other region to swap

Region.translate(self: skia.Region, dx: int, dy: int) → skia.Region

Offsets Region by ivector (dx, dy).

Has no effect if Region is empty. If Region is empty, returns empty region.

Dx:: x-axis offset
Dy:: y-axis offset

Region.writeToMemory(self: skia.Region) → SkData

Writes Region to Data.

Returns:: Data

Attributes

Region.kDifference_Op = <Op.kDifference_Op: 0>

Region.kIntersect_Op = <Op.kIntersect_Op: 1>

Region.kLastOp = <Op.kReplace_Op: 5>

Region.kOpCnt = 6

Region.kReplace_Op = <Op.kReplace_Op: 5>

Region.kReverseDifference_Op = <Op.kReverseDifference_Op: 4>

Region.kUnion_Op = <Op.kUnion_Op: 2>

Region.kXOR_Op = <Op.kXOR_Op: 3>