=head1 NAME

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

=head1 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;

=head1 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.

=head1 API

=over

=item 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:

=over

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

Creates a rectangular region with inclusive-inclusive coordinates.

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

Same as C<rect> but using the I<box> semantics.

=item polygon => \@POINTS, fillMode = 0

Creates a polygon shape with vertices given in C<@POINTS>, and using
the optional fillMode ( see L<Drawable/fillMode> ).

=item 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.

=back

=item 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.

=item 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.

=item combine REGION, OPERATION = rgnop::Copy

Applies one of the following set operations to the region:

=over

=item rgnop::Copy

Makes a copy of the REGION

=item rgnop::Intersect

The resulting region is an intersection of the two regions.

=item rgnop::Union

The resulting region is a union of the two regions.

=item rgnop::Xor

Performs XOR operation on the two regions.

=item rgnop::Diff

The resulting region is a difference between the two regions.

=back

=item dup

Creates a duplicate region object

=item get_boxes

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

=item get_handle

Returns the system handle for the region

=item equals REGION

Returns true if the regions are equal, false otherwise.

=item 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.

=item is_empty

Returns true if the region is empty, false otherwise.

=item offset DX, DY

Shifts the region vertically and/or horizontally

=item point_inside X, Y

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

=item 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 C<rgn::Outside> constant has the value of 0.

=back

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::Drawable>, L<Prima::Drawable::Path>
