Provided by: libsdl-perl_2.2.5-1build2_amd64 bug

NAME

       SDL::Game::Rect - SDL::Game object for storing and manipulating rectangular coordinates

SYNOPSIS

          my $rect = SDL::Game::Rect->new( 10, 20, 5, 5 );  # top, left, width, height

          my $another_rect = SDL::Game::Rect->new( 10, 30, 5, 8);

          if ( $rect->collide_rect ($another_rect) ) {
              print "collision!!!\n";

              $rect->move($new_x, $new_y);
          }

WARNING

       This module is ***EXPERIMENTAL***

       It is being designed for the new SDL Perl API, so things may change at any given time. In
       particular, pay attention to the caveat below: that'll definitely go away in the future
       and will require changes on your account.

   USAGE CAVEAT
       SDL Perl uses some intricate XS magic that doesn't allow us to just use base 'SDL::Rect'.
       So, even though we provide the very same accessors (and more! see below), other SDL
       modules that take a SDL::Rect object as argument won't accept passing an SDL::Game::Rect
       (yet). To work around this we provide the "rect()" method, which returns a vanilla
       "SDL::Rect" object with the appropriate dimensions. So, for example, if $gamerect is a
       "SDL::Game::Rect" object, then instead of doing something like this will trigger a fatal
       error:

          $app->update( $gamerect );  # this will fail!

       instead, you should do this (for now):

           $app->update( $gamerect->rect ); # ok!

       The SDL Perl development team is working to fix this. If you want to help, please join us
       in the mailing list or in #sdl on irc.perl.org.

DESCRIPTION

       "SDL::Game::Rect" 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 "SDL::Rect objects".

       All "SDL::Game::Rect" methods that change either position or size of a Rect are "in-
       place". This means they change the Rect whose method was called and return nothing.

   ATTRIBUTES
       All Rect attributes are acessors, meaning you can get them by name, and set them by
       passing a value:

          $rect->left(15);
          $rect->left;       # 15

       The Rect object has several attributes which can be used to resize, move and align the
       Rect.

       ·   width, w - gets/sets object's width

       ·   height, h - gets/sets object's height

       ·   left, x - moves the object left position to match the given coordinate

       ·   top, y  - moves the object top position to match the given coordinate

       ·   bottom - moves the object bottom position to match the given coordinate

       ·   right - moves the object right position to match the given coordinate

       ·   center_x - moves the object's horizontal center to match the given coordinate

       ·   center_y - moves the object's vertical center to match the given coordinate

       Some of the attributes above can be fetched or set in pairs:

         $rect->top_left(10, 15);   # top is now 10, left is now 15

         my ($width, $height) = $rect->size;

       ·   size - gets/sets object's size (width, height)

       ·   top_left - gets/sets object's top and left positions

       ·   mid_left - gets/sets object's vertical center and left positions

       ·   bottom_left - gets/sets object's bottom and left positions

       ·   center - gets/sets object's center (horizontal(x), vertical(y))

       ·   top_right - gets/sets object's top and right positions

       ·   mid_right - gets/sets object's vertical center and right positions

       ·   bottom_right - gets/sets object's bottom and right positions

       ·   mid_top - gets/sets object's horizontal center and top positions

       ·   mid_bottom - gets/sets object's horizontal center and bottom positions

   METHODS
       Methods denoted as receiving Rect objects can receive either "<SDL::Game::Rect"> or raw
       "<SDL::Rect"> objects.

       new ($left, $top, $width, $height)

       Returns a new Rect object with the given coordinates. If any value is omitted (by passing
       undef), 0 is used instead.

       copy

       duplicate

       Returns a new Rect object having the same position and size as the original

       move(x, y)

       Moves current Rect by the given offset. The x and y arguments can be any integer value,
       positive or negative.

       inflate(x, y)

       Grows or shrinks the rectangle. Rect's size is changed by the given offset. The rectangle
       remains centered around its current center. Negative values make ita shrinked rectangle
       instead.

       clamp($rect)

       Moves original Rect 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.

       clip($rect)

       Turns the original Rect into the intersection between it and the Rect object passed as an
       argument. That is, the original Rect gets cropped to be completely inside the Rect object
       passed as an argument. If the two rectangles do not overlap to begin with, the Rect bcomes
       zero-sized, retaining its the original (x,y) coordinates.

       union($rect)

       union( $rect1, $rect2, ... )

       Makes the original Rect big enough to completely cover the area of itself and all other
       Rects passed as an argument. As the Rects can have any given dimensions and positions,
       there may be area inside the new Rect that is not covered by the originals.

       fit($rect)

       Moves and resizes the original Rect to fit the Rect object passed as an argument. The
       aspect ratio of the original Rect is preserved, so it may be smaller than the target in
       either width or height.

       normalize

       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.

       contains($rect)

       Returns true (non-zero) when the argument is completely inside the Rect. Otherwise returns
       undef.

       collide_point(x, y)

       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.

       collide_rect($rect)

       Returns true (non-zero) if any portion of either rectangles overlap (except for the
       top+bottom or left+right edges).

       collide_list( [$rect1, $rect2, ...] )

       Test whether the rectangle collides with any in a sequence of rectangles, passed as an
       ARRAY REF. The index of the first collision found is returned. Returns undef if no
       collisions are found.

       collide_list_all( [$rect1, $rect2, ...] )

       Returns an ARRAY REF of all the indices that contain rectangles that collide with the
       Rect. If no intersecting rectangles are found, an empty list ref is returned.

       collide_hash( {key1 => $rect1, key2 => $rect2, ...} )

       Receives a HASH REF 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).

       collide_hash_all( {key1 => $rect1, key2 => $rect2, ...} )

       Returns a HASH REF of all the key and value pairs that intersect with the Rect. If no
       collisions are found an empty hash ref is returned.

AUTHOR

       Breno G. de Oliveira, "<garu at cpan.org>"

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.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc SDL::Game::Rect

ACKNOWLEDGEMENTS

       Many thanks to all SDL_Perl contributors, and to the authors of pygame.rect, in which this
       particular module is heavily based.

COPYRIGHT & LICENSE

       Copyright 2009 The SDL Perl Development Team, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       perl, SDL, SDL::Rect