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


   $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;


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.



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 = 0

Creates a polygon shape with vertices given in @POINTS, 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.

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.


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:


Makes a copy of the REGION


The resulting region is an intersection of the two regions.


The resulting region is a union of the two regions.


Performs XOR operation on the two regions.


The resulting region is a difference between the two regions.


Creates a duplicate region object


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


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.


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:


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


Dmitry Karasik, <>.


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