Provided by: libsdl-perl_2.548-5build1_amd64 bug

NAME

       SDLx::Rect - SDL extension for storing and manipulating rectangular coordinates

CATEGORY

       Extension

SYNOPSIS

       SDLx::Rect works as a SDL::Rect in the lower layer (SDL::*) but provides more methods to users.

               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

DESCRIPTION

       "SDLx::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 "SDLx::Rect" methods that change either position or size of a Rect return a new copy of the Rect with
       the affected changes. The original Rect is not modified. If you wish to modify the current Rect object,
       you can use the equivalent "in-place" methods that do not return but instead affects the original Rect.
       These "in-place" methods are denoted with the "ip" suffix. Note that changing a Rect's attribute is
       always an in-place operation.

   ATTRIBUTES
       All Rect attributes are accessors, 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

       •   centerx - moves the object's horizontal center to match the given coordinate

       •   centery - moves the object's vertical center to match the given coordinate

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

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

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

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

       •   topleft - gets/sets object's top and left positions

       •   midleft - gets/sets object's vertical center and left positions

       •   bottomleft - gets/sets object's bottom and left positions

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

       •   topright - gets/sets object's top and right positions

       •   midright - gets/sets object's vertical center and right positions

       •   bottomright - gets/sets object's bottom and right positions

       •   midtop - gets/sets object's horizontal center and top positions

       •   midbottom - gets/sets object's horizontal center and bottom positions

   METHODS
       Methods denoted as receiving Rect objects can receive either "<SDLx::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)

       Returns a new Rect that is moved by the given offset. The x and y arguments can  be  any  integer  value,
       positive or negative.

       move_ip(x, y)

       Same as "<move"> above, but moves the current Rect in place and returns nothing.

       inflate(x, y)

       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.

       inflate_ip(x, y)

       Same as "<inflate"> above, but grows/shrinks the current Rect in place and returns nothing.

       clamp($rect)

       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.

       clamp_ip($rect)

       Same as "<clamp"> above, but moves the current Rect in place and returns nothing.

       clip($rect)

       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.

       clip_ip($rect)

       Same as "<clip"> 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.

       union($rect)

       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.

       union_ip($rect)

       Same as "<union"> above, but resizes the current Rect in place and returns nothing.

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

       Returns the union of one rectangle with a sequence of many rectangles, passed as an ARRAY REF.

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

       Same as "<unionall"> above, but resizes the current Rect in place and returns nothing.

       fit($rect)

       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.

       fit_ip($rect)

       Same as "<fit"> above, but moves/resizes the current Rect in place and returns nothing.

       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. This
       method returns nothing.

       contains($rect)

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

       collidepoint(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.

       colliderect($rect)

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

       collidelist( [$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.

       collidelistall( [$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.

       collidehash( {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).

       collidehashall( {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.

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 SDLx::Rect

AUTHORS

       See "AUTHORS" in SDL.

ACKNOWLEDGEMENTS

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

COPYRIGHT & LICENSE

       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, SDL::Game

perl v5.38.2                                       2024-03-31                              pods::SDLx::Rect(3pm)