.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "pods::SDLx::Rect 3pm"
.TH pods::SDLx::Rect 3pm "2016-09-18" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SDLx::Rect \- SDL extension for storing and manipulating rectangular coordinates
.SH "CATEGORY"
.IX Header "CATEGORY"
Extension
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
SDLx::Rect works as a SDL::Rect in the lower layer (SDL::*) but provides more methods to users.
.PP
.Vb 1
\&        use SDLx::Rect; #instead of SDL::Rect
\&
\&        my $rect = SDLx::Rect\->new( $x, $y, $w, $h); #same as SDL::Rect
\&
\&        ...
\&
\&        SDL::Video::fill_rect( .. , $rect, ...); # use like SDL::Rect
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`SDLx::Rect\*(C'\fR object are used to store and manipulate rectangular areas. Rect objects are created from a combination of left (or x), top (or y), width (or w) and height (or h) values, just like raw \f(CW\*(C`SDL::Rect objects\*(C'\fR.
.PP
All \f(CW\*(C`SDLx::Rect\*(C'\fR methods that change either position or size of a Rect return \fBa new copy\fR of the Rect with the affected changes. The original Rect is \fBnot\fR modified. If you wish to modify the current Rect object, you can use the equivalent \*(L"in-place\*(R" methods that do not return but instead affects the original Rect. These \*(L"in-place\*(R" methods are denoted with the \*(L"ip\*(R" suffix. Note that changing a Rect's attribute is \fIalways\fR an in-place operation.
.SS "\s-1ATTRIBUTES\s0"
.IX Subsection "ATTRIBUTES"
All Rect attributes are accessors, meaning you can get them by name, and set them by passing a value:
.PP
.Vb 2
\&   $rect\->left(15);
\&   $rect\->left;       # 15
.Ve
.PP
The Rect object has several attributes which can be used to resize, move and align the Rect.
.IP "\(bu" 4
width, w \- gets/sets object's width
.IP "\(bu" 4
height, h \- gets/sets object's height
.IP "\(bu" 4
left, x \- moves the object left position to match the given coordinate
.IP "\(bu" 4
top, y  \- moves the object top position to match the given coordinate
.IP "\(bu" 4
bottom \- moves the object bottom position to match the given coordinate
.IP "\(bu" 4
right \- moves the object right position to match the given coordinate
.IP "\(bu" 4
centerx \- moves the object's horizontal center to match the given coordinate
.IP "\(bu" 4
centery \- moves the object's vertical center to match the given coordinate
.PP
Some of the attributes above can be fetched or set in pairs:
.PP
.Vb 1
\&  $rect\->topleft(10, 15);   # top is now 10, left is now 15
\&
\&  my ($width, $height) = $rect\->size;
.Ve
.IP "\(bu" 4
size \- gets/sets object's size (width, height)
.IP "\(bu" 4
topleft \- gets/sets object's top and left positions
.IP "\(bu" 4
midleft \- gets/sets object's vertical center and left positions
.IP "\(bu" 4
bottomleft \- gets/sets object's bottom and left positions
.IP "\(bu" 4
center \- gets/sets object's center (horizontal(x), vertical(y))
.IP "\(bu" 4
topright \- gets/sets object's top and right positions
.IP "\(bu" 4
midright \- gets/sets object's vertical center and right positions
.IP "\(bu" 4
bottomright \- gets/sets object's bottom and right positions
.IP "\(bu" 4
midtop \- gets/sets object's horizontal center and top positions
.IP "\(bu" 4
midbottom \- gets/sets object's horizontal center and bottom positions
.SS "\s-1METHODS \s0"
.IX Subsection "METHODS "
Methods denoted as receiving Rect objects can receive either \f(CW\*(C`<SDLx::Rect\*(C'\fR> or raw \f(CW\*(C`<SDL::Rect\*(C'\fR> objects.
.PP
\fInew ($left, \f(CI$top\fI, \f(CI$width\fI, \f(CI$height\fI)\fR
.IX Subsection "new ($left, $top, $width, $height)"
.PP
Returns a new Rect object with the given coordinates. If any value is omitted (by passing undef), 0 is used instead.
.PP
\fIcopy\fR
.IX Subsection "copy"
.PP
\fIduplicate\fR
.IX Subsection "duplicate"
.PP
Returns a new Rect object having the same position and size as the original
.PP
\fImove(x, y)\fR
.IX Subsection "move(x, y)"
.PP
Returns a new Rect that is moved by the given offset. The x and y arguments can be any integer value, positive or negative.
.PP
\fImove_ip(x, y)\fR
.IX Subsection "move_ip(x, y)"
.PP
Same as \f(CW\*(C`<move\*(C'\fR> above, but moves the current Rect in place and returns nothing.
.PP
\fIinflate(x, y)\fR
.IX Subsection "inflate(x, y)"
.PP
Grows or shrinks the rectangle. Returns a new Rect with the size changed by the given offset. The rectangle remains centered around its current center. Negative values will return a shrunken rectangle instead.
.PP
\fIinflate_ip(x, y)\fR
.IX Subsection "inflate_ip(x, y)"
.PP
Same as \f(CW\*(C`<inflate\*(C'\fR> above, but grows/shrinks the current Rect in place and returns nothing.
.PP
\fIclamp($rect)\fR
.IX Subsection "clamp($rect)"
.PP
Returns a new Rect moved to be completely inside the Rect object passed as an argument. If the current Rect is too large to fit inside the passed Rect, it is centered inside it, but its size is not changed.
.PP
\fIclamp_ip($rect)\fR
.IX Subsection "clamp_ip($rect)"
.PP
Same as \f(CW\*(C`<clamp\*(C'\fR> above, but moves the current Rect in place and returns nothing.
.PP
\fIclip($rect)\fR
.IX Subsection "clip($rect)"
.PP
Returns a new Rect with the intersection between the two Rect objects, that is, returns a new Rect cropped to be completely inside the Rect object passed as an argument. If the two rectangles do not overlap to begin with, a Rect with 0 size is returned, in the original Rect's (x,y) coordinates.
.PP
\fIclip_ip($rect)\fR
.IX Subsection "clip_ip($rect)"
.PP
Same as \f(CW\*(C`<clip\*(C'\fR> above, but crops the current Rect in place and returns nothing. As the original method, the Rect becomes zero-sized if the two rectangles do not overlap to begin with, retaining its (x, y) coordinates.
.PP
\fIunion($rect)\fR
.IX Subsection "union($rect)"
.PP
Returns a new rectangle that completely covers the area of the current Rect and the one passed as an argument. There may be area inside the new Rect that is not covered by the originals.
.PP
\fIunion_ip($rect)\fR
.IX Subsection "union_ip($rect)"
.PP
Same as \f(CW\*(C`<union\*(C'\fR> above, but resizes the current Rect in place and returns nothing.
.PP
\fIunionall( [$rect1, \f(CI$rect2\fI, ...] )\fR
.IX Subsection "unionall( [$rect1, $rect2, ...] )"
.PP
Returns the union of one rectangle with a sequence of many rectangles, passed as an \s-1ARRAY REF.\s0
.PP
\fIunionall_ip( [$rect1, \f(CI$rect2\fI, ...] )\fR
.IX Subsection "unionall_ip( [$rect1, $rect2, ...] )"
.PP
Same as \f(CW\*(C`<unionall\*(C'\fR> above, but resizes the current Rect in place and returns nothing.
.PP
\fIfit($rect)\fR
.IX Subsection "fit($rect)"
.PP
Returns a new Rect moved and resized to fit the Rect object passed as an argument. The aspect ratio of the original Rect is preserved, so the new rectangle may be smaller than the target in either width or height.
.PP
\fIfit_ip($rect)\fR
.IX Subsection "fit_ip($rect)"
.PP
Same as \f(CW\*(C`<fit\*(C'\fR> above, but moves/resizes the current Rect in place and returns nothing.
.PP
\fInormalize\fR
.IX Subsection "normalize"
.PP
Corrects negative sizes, flipping width/height of the Rect if they have a negative size. No repositioning is made so the rectangle will remain in the same place, but the negative sides will be swapped. This method returns nothing.
.PP
\fIcontains($rect)\fR
.IX Subsection "contains($rect)"
.PP
Returns true (non-zero) when the argument is completely inside the Rect. Otherwise returns undef.
.PP
\fIcollidepoint(x, y)\fR
.IX Subsection "collidepoint(x, y)"
.PP
Returns true (non-zero) if the given point is inside the Rect, otherwise returns undef. A point along the right or bottom edge is not considered to be inside the rectangle.
.PP
\fIcolliderect($rect)\fR
.IX Subsection "colliderect($rect)"
.PP
Returns true (non-zero) if any portion of either rectangles overlap (except for the top+bottom or left+right edges).
.PP
\fIcollidelist( [$rect1, \f(CI$rect2\fI, ...] )\fR
.IX Subsection "collidelist( [$rect1, $rect2, ...] )"
.PP
Test whether the rectangle collides with any in a sequence of rectangles, passed as an \s-1ARRAY REF.\s0 The index of the first collision found is returned. Returns undef if no collisions are found.
.PP
\fIcollidelistall( [$rect1, \f(CI$rect2\fI, ...] )\fR
.IX Subsection "collidelistall( [$rect1, $rect2, ...] )"
.PP
Returns an \s-1ARRAY REF\s0 of all the indices that contain rectangles that collide with the Rect. If no intersecting rectangles are found, an empty list ref is returned.
.PP
\fIcollidehash( {key1 => \f(CI$rect1\fI, key2 => \f(CI$rect2\fI, ...} )\fR
.IX Subsection "collidehash( {key1 => $rect1, key2 => $rect2, ...} )"
.PP
Receives a \s-1HASH REF\s0 and returns the a (key, value) list with the key and value of the first hash item that collides with the Rect. If no collisions are found, returns (undef, undef).
.PP
\fIcollidehashall( {key1 => \f(CI$rect1\fI, key2 => \f(CI$rect2\fI, ...} )\fR
.IX Subsection "collidehashall( {key1 => $rect1, key2 => $rect2, ...} )"
.PP
Returns a \s-1HASH REF\s0 of all the key and value pairs that intersect with the Rect. If no collisions are found an empty hash ref is returned.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to the bug tracker. I will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc SDLx::Rect
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
See \*(L"\s-1AUTHORS\*(R"\s0 in \s-1SDL\s0.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Many thanks to the authors of pygame.rect, in which this particular module is heavily based.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl, \s-1SDL\s0, SDL::Rect, SDL::Game