PageRenderTime 9ms CodeModel.GetById 1ms app.highlight 2ms RepoModel.GetById 2ms app.codeStats 0ms

/lib/pods/SDLx/Rect.pod

http://github.com/PerlGameDev/SDL
Unknown | 222 lines | 108 code | 114 blank | 0 comment | 0 complexity | f97497e83947d1ac3c3e0f05e6f74649 MD5 | raw file
  1
  2=head1 NAME
  3
  4SDLx::Rect - SDL extension for storing and manipulating rectangular coordinates
  5
  6=head1 CATEGORY
  7
  8Extension
  9
 10=head1 SYNOPSIS
 11
 12SDLx::Rect works as a SDL::Rect in the lower layer (SDL::*) but provides more methods to users.
 13
 14	use SDLx::Rect; #instead of SDL::Rect
 15
 16	my $rect = SDLx::Rect->new( $x, $y, $w, $h); #same as SDL::Rect
 17
 18	...
 19
 20	SDL::Video::fill_rect( .. , $rect, ...); # use like SDL::Rect
 21
 22
 23=head1 DESCRIPTION
 24
 25C<< 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 C<< SDL::Rect objects >>.
 26
 27All C<< SDLx::Rect >> methods that change either position or size of a Rect return B<a new copy> of the Rect with the affected changes. The original Rect is B<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 I<always> an in-place operation.
 28
 29
 30=head2 ATTRIBUTES
 31
 32All Rect attributes are accessors, meaning you can get them by name, and set them by passing a value:
 33
 34   $rect->left(15);
 35   $rect->left;       # 15
 36
 37The Rect object has several attributes which can be used to resize, move and align the Rect.
 38
 39
 40=over 4
 41
 42=item * width, w - gets/sets object's width
 43
 44=item * height, h - gets/sets object's height
 45
 46=item * left, x - moves the object left position to match the given coordinate
 47
 48=item * top, y  - moves the object top position to match the given coordinate
 49
 50=item * bottom - moves the object bottom position to match the given coordinate
 51
 52=item * right - moves the object right position to match the given coordinate
 53
 54=item * centerx - moves the object's horizontal center to match the given coordinate
 55
 56=item * centery - moves the object's vertical center to match the given coordinate
 57
 58=back
 59
 60Some of the attributes above can be fetched or set in pairs:
 61
 62  $rect->topleft(10, 15);   # top is now 10, left is now 15
 63
 64  my ($width, $height) = $rect->size;
 65
 66
 67=over 4
 68
 69=item * size - gets/sets object's size (width, height)
 70
 71=item * topleft - gets/sets object's top and left positions
 72
 73=item * midleft - gets/sets object's vertical center and left positions
 74
 75=item * bottomleft - gets/sets object's bottom and left positions
 76
 77=item * center - gets/sets object's center (horizontal(x), vertical(y))
 78
 79=item * topright - gets/sets object's top and right positions
 80
 81=item * midright - gets/sets object's vertical center and right positions
 82
 83=item * bottomright - gets/sets object's bottom and right positions
 84
 85=item * midtop - gets/sets object's horizontal center and top positions
 86
 87=item * midbottom - gets/sets object's horizontal center and bottom positions
 88
 89=back
 90
 91
 92=head2 METHODS 
 93
 94Methods denoted as receiving Rect objects can receive either C<<SDLx::Rect>> or raw C<<SDL::Rect>> objects.
 95
 96=head3 new ($left, $top, $width, $height)
 97
 98Returns a new Rect object with the given coordinates. If any value is omitted (by passing undef), 0 is used instead.
 99
100=head3 copy
101
102=head3 duplicate
103
104Returns a new Rect object having the same position and size as the original
105
106=head3 move(x, y)
107
108Returns a new Rect that is moved by the given offset. The x and y arguments can be any integer value, positive or negative.
109
110=head3 move_ip(x, y)
111
112Same as C<<move>> above, but moves the current Rect in place and returns nothing.
113
114=head3 inflate(x, y)
115
116Grows 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.
117
118=head3 inflate_ip(x, y)
119
120Same as C<<inflate>> above, but grows/shrinks the current Rect in place and returns nothing.
121
122=head3 clamp($rect)
123
124Returns 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.
125
126=head3 clamp_ip($rect)
127
128Same as C<<clamp>> above, but moves the current Rect in place and returns nothing.
129
130=head3 clip($rect)
131
132Returns 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.
133
134=head3 clip_ip($rect)
135
136Same as C<<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.
137
138=head3 union($rect)
139
140Returns 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.
141
142=head3 union_ip($rect)
143
144Same as C<<union>> above, but resizes the current Rect in place and returns nothing.
145
146=head3 unionall( [$rect1, $rect2, ...] )
147
148Returns the union of one rectangle with a sequence of many rectangles, passed as an ARRAY REF.
149
150=head3 unionall_ip( [$rect1, $rect2, ...] )
151
152Same as C<<unionall>> above, but resizes the current Rect in place and returns nothing.
153
154=head3 fit($rect)
155
156Returns 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. 
157
158=head3 fit_ip($rect)
159
160Same as C<<fit>> above, but moves/resizes the current Rect in place and returns nothing.
161
162=head3 normalize
163
164Corrects 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.
165
166=head3 contains($rect)
167
168Returns true (non-zero) when the argument is completely inside the Rect. Otherwise returns undef.
169
170=head3 collidepoint(x, y)
171
172Returns 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.
173
174=head3 colliderect($rect)
175
176Returns true (non-zero) if any portion of either rectangles overlap (except for the top+bottom or left+right edges).
177
178=head3 collidelist( [$rect1, $rect2, ...] )
179
180Test 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.
181
182=head3 collidelistall( [$rect1, $rect2, ...] )
183
184Returns 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. 
185
186=head3 collidehash( {key1 => $rect1, key2 => $rect2, ...} )
187
188Receives 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).
189
190=head3 collidehashall( {key1 => $rect1, key2 => $rect2, ...} )
191
192Returns 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. 
193
194
195=head1 BUGS
196
197Please 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.
198
199
200=head1 SUPPORT
201
202You can find documentation for this module with the perldoc command.
203
204    perldoc SDLx::Rect
205
206=head1 AUTHORS
207
208See L<SDL/AUTHORS>.
209
210=head1 ACKNOWLEDGEMENTS
211
212Many thanks to the authors of pygame.rect, in which this particular module is heavily based.
213
214=head1 COPYRIGHT & LICENSE
215
216This program is free software; you can redistribute it and/or modify it
217under the same terms as Perl itself.
218
219
220=head1 SEE ALSO
221
222perl, L<SDL>, L<SDL::Rect>, L<SDL::Game>