NAME

Prima::Region - generic shapes for clipping and hit testing

SYNOPSIS

$empty = Prima::Region->new;

$rect  = Prima::Region->new( rect => [ 10, 10, 20, 20 ]);
$rect  = Prima::Region->new( box  => [ 10, 10, 10, 10 ]); # same

$poly  = Prima::Region->new( polygon => [ 0, 0, 100, 0, 100, 100 ]);

$bits  = Prima::Region->new( image => $image );

$drawable-> region( $rect );

my $rgn = $drawable->region;
$rgn->image->save('region.png') if $rgn;

DESCRIPTION

The Prima::Region class is a descendant of the Prima::Component class. A Prima::Region object is a representation of a generic shape that can be applied to a drawable and checked whether points are within its boundaries.

API

new %OPTIONS

Creates a new region object. If called without any options then the resulting region will be empty The following options can be used:

rect => [ X1, Y1, X2, Y2 ]

Creates a rectangular region with inclusive-inclusive coordinates.

box => [ X, Y, WIDTH, HEIGHT ]

Same as rect but using the box semantics.

polygon => \@POINTS, fillMode = fm::Overlay | fm::Winding

Creates a polygon shape with vertices given in @POINTS, and using the optional fillMode ( see "fillMode" in Drawable ).

polygons => [\@POINTS, \@POINTS, ...], fillMode = fm::Overlay | fm::Winding

Creates a polygon shape with set of polygon vertices, and using the optional fillMode ( see "fillMode" in Drawable ).

image => IMAGE

Creates a region from a 1-bit image. If the image contains no pixels that are set to 1, the resulting region is created as an empty region.

matrix => [A,B,C,D,X,Y]

Applies the matrix to the input. Since the regions are not subject to transformations applied via Drawable.region, this helper option can be useful for generic transformations.

bitmap with_offset => 0, type => dbt::Bitmap

Paints the region on a newly created bitmap and returns it. By default, the region offset is not included.

box

Returns the (X,Y,WIDTH,HEIGHT) bounding box that encloses the smallest possible rectangle, or (0,0,0,0) if the region is empty.

combine REGION, OPERATION = rgnop::Copy

Applies one of the following set operations to the region:

rgnop::Copy

Makes a copy of the REGION

rgnop::Intersect

The resulting region is an intersection of the two regions.

rgnop::Union

The resulting region is a union of the two regions.

rgnop::Xor

Performs XOR operation on the two regions.

rgnop::Diff

The resulting region is a difference between the two regions.

dup

Creates a duplicate region object

get_boxes

Returns a Prima::array object filled with 4-integer tuples, where each is a box defined as a (x,y,width,height) tuple.

get_handle

Returns the system handle for the region

equals REGION

Returns true if the regions are equal, false otherwise.

image with_offset => 0, type => dbt::Bitmap

Paints the region on a newly created image and returns it. By default, the region offset is not included.

is_empty

Returns true if the region is empty, false otherwise.

offset DX, DY

Shifts the region vertically and/or horizontally

point_inside X, Y

Returns true if the (X,Y) point is inside the region

rect_inside X1,Y1,X2,Y2

Checks whether a rectangle given by the inclusive-inclusive coordinates is inside, outside, or partially covered by the region. The return value can be one of these flags:

rgn::Inside
rgn::Outside
rgn::Partially

where the rgn::Outside constant has the value of 0.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

Prima, Prima::Drawable, Prima::Drawable::Path