=head1 NAME

Prima::types - builtin types

=head1 DESCRIPTION

This document describes the auxiliary second-citizen classes that are used as
results of Prima methods and accepted as inputs. Objects that instantiate from
these classes are usually never created manually. The names of some of these
classes begin with a lower-case letter, to underscore their auxiliary nature.

=head1 Prima::array

An overloaded C array that can be used transparently as a normal perl array.
The array can only hold numbers.  The reason the C<Prima::array> class exists
is so Prima methods won't need to do expensive conversions between a perl array
of scalars to a C array of integers or floats.

=over

=item new LETTER = [idsS], BUF = undef

Creates a new C array with the type of either int, double, short, or unsigned
short. There are also methods C<new_int>, C<new_double>, C<new_short>, and
C<new_ushort> that do the same.

BUF, a normal perl string, can be used to initialize the array, if any (and can
be pre-populated with pack()). Otherwise, an array is created empty.

=item is_array SCALAR

Checks whether the SCALAR is a C<Prima::array> object.

=item substr OFFSET, LENGTH, REPLACEMENT

Emulates perl's C<substr> except operates not on characters but on the
individual numeric entries of the array.  Returns a new C<Prima::array> object.

=item append ARRAY

Assuming that two arrays have the same type, appends the ARRAY's contents to
its content.

=item clone

Clones the array.

=back

=head1 Prima::matrix

An array of 6 doubles with some helper methods attached.

=over

=item A,B,C,D,X,Y

Named accessory properties for the 6 members.
The members can just as well be accessed directly with the array syntax.

=item clone

Clones the matrix object

=item identity

Sets the matrix to C<Prima::matrix::identity>, or (1,0,0,1,0,0)

=item inverse_transform @POINTS | $POINTS_ARRAY

Applies the inverse matrix tranformations to an array or an arrayref of points
and returns the result matrix in the same format (i e array for array, ref for
ref).

=item new [ @ARRAY ]

Creates a new object and optionally initializes it with @ARRAY

=item multiply MATRIX

Multiplies the matrices and stores the result

=item rotate ANGLE

Rotates the matrix

=item scale MX,MY

Scales the matrix

=item shear DX,DY

Shears the matrix

=item set @ARRAY

Assigns all the 6 members at once

=item translate DX,DY

Translates the matrix

=item transform @POINTS | $POINTS_ARRAY

Applies matrix tranformations to an array or arrayref of points and returns
the result matrix in the same format (i e array for array, ref for ref).

=back

See also: L<Prima::Matrix>

=head1 Prima::Matrix

Same as C<Prima::matrix> but explicitly binds to drawable objects so that
all changes to the matrix object are immediately reflected in the drawable.

Features all the methods available to C<Prima::matrix> (except C<apply>), plus
the ones described below.

=over

=item new CANVAS

Creates a new matrix object instance

=item canvas DRAWABLE

Accesses the associated drawable object

=item get

Returns the current matrix

=item reset

Sets the matrix to C<Prima::matrix::identity>, or (1,0,0,1,0,0)

=item save, restore

Saves and restores the matrix content in the internal stack

=back

=head1 Prima::rect

Represents a rectangular object either as a I<rectangle> ( X1,Y1,X2,Y2 ) or a I<box> ( X,Y,WIDTH,HEIGHT ).

=over

=item box

Returns X, Y, WIDTH, HEIGHT

=item clone

Clones the object

=item enlarge N

Enlarges the rectangle by N

=item inclusive

Rectangle itself is agnostic of its 2D presentation, but assuming the coordinates
are inclusive-exclusive, C<inclusive> returns X1,Y1,X2,Y2 as the inclusive-inclusive rectangle.

=item intersect RECT

Intersects with the RECT rectangle and stores the result

=item is_empty

Returns true if the rectangle width and height are zero

=item is_equal RECT

Returns true if both rectangles are equal

=item new () | (WIDTH,HEIGHT) | (X1,Y1,X2,Y2)

Creates a new object assuming the rectangle syntax

=item new_box X,Y,WIDTH,HEIGHT

Creates new object assuming the box syntax

=item origin

Returns X and Y

=item shrink N

Shrinks the rectangle by N

=item size

Returns the WIDTH and HEIGHT of the rectangle

=item union RECT

Joins the rectangle with the RECT rectangle and stores the result

=back

=head1 AUTHOR

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

=head1 SEE ALSO

L<Prima>
