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.

  1. __init__(self: skia.Region) -> None

    Constructs an empty Region.

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

  2. __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

  3. __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.

  1. 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

  2. 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

  3. 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.

  1. 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

  2. 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.

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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.

  1. 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

  2. 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:
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>