1SDLx::Rect(3)         User Contributed Perl Documentation        SDLx::Rect(3)
2
3
4

NAME

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

CATEGORY

10       Extension
11

SYNOPSIS

13       SDLx::Rect works as a SDL::Rect in the lower layer (SDL::*) but
14       provides more methods to users.
15
16               use SDLx::Rect; #instead of SDL::Rect
17
18               my $rect = SDLx::Rect->new( $x, $y, $w, $h); #same as SDL::Rect
19
20               ...
21
22               SDL::Video::fill_rect( .. , $rect, ...); # use like SDL::Rect
23

DESCRIPTION

25       "SDLx::Rect" object are used to store and manipulate rectangular areas.
26       Rect objects are created from a combination of left (or x), top (or y),
27       width (or w) and height (or h) values, just like raw "SDL::Rect
28       objects".
29
30       All "SDLx::Rect" methods that change either position or size of a Rect
31       return a new copy of the Rect with the affected changes. The original
32       Rect is not modified. If you wish to modify the current Rect object,
33       you can use the equivalent "in-place" methods that do not return but
34       instead affects the original Rect. These "in-place" methods are denoted
35       with the "ip" suffix. Note that changing a Rect's attribute is always
36       an in-place operation.
37
38   ATTRIBUTES
39       All Rect attributes are accessors, meaning you can get them by name,
40       and set them by passing a value:
41
42          $rect->left(15);
43          $rect->left;       # 15
44
45       The Rect object has several attributes which can be used to resize,
46       move and align the Rect.
47
48       •   width, w - gets/sets object's width
49
50       •   height, h - gets/sets object's height
51
52       •   left, x - moves the object left position to match the given
53           coordinate
54
55       •   top, y  - moves the object top position to match the given
56           coordinate
57
58       •   bottom - moves the object bottom position to match the given
59           coordinate
60
61       •   right - moves the object right position to match the given
62           coordinate
63
64       •   centerx - moves the object's horizontal center to match the given
65           coordinate
66
67       •   centery - moves the object's vertical center to match the given
68           coordinate
69
70       Some of the attributes above can be fetched or set in pairs:
71
72         $rect->topleft(10, 15);   # top is now 10, left is now 15
73
74         my ($width, $height) = $rect->size;
75
76       •   size - gets/sets object's size (width, height)
77
78       •   topleft - gets/sets object's top and left positions
79
80       •   midleft - gets/sets object's vertical center and left positions
81
82       •   bottomleft - gets/sets object's bottom and left positions
83
84       •   center - gets/sets object's center (horizontal(x), vertical(y))
85
86       •   topright - gets/sets object's top and right positions
87
88       •   midright - gets/sets object's vertical center and right positions
89
90       •   bottomright - gets/sets object's bottom and right positions
91
92       •   midtop - gets/sets object's horizontal center and top positions
93
94       •   midbottom - gets/sets object's horizontal center and bottom
95           positions
96
97   METHODS
98       Methods denoted as receiving Rect objects can receive either
99       "<SDLx::Rect"> or raw "<SDL::Rect"> objects.
100
101       new ($left, $top, $width, $height)
102
103       Returns a new Rect object with the given coordinates. If any value is
104       omitted (by passing undef), 0 is used instead.
105
106       copy
107
108       duplicate
109
110       Returns a new Rect object having the same position and size as the
111       original
112
113       move(x, y)
114
115       Returns a new Rect that is moved by the given offset. The x and y
116       arguments can be any integer value, positive or negative.
117
118       move_ip(x, y)
119
120       Same as "<move"> above, but moves the current Rect in place and returns
121       nothing.
122
123       inflate(x, y)
124
125       Grows or shrinks the rectangle. Returns a new Rect with the size
126       changed by the given offset. The rectangle remains centered around its
127       current center. Negative values will return a shrunken rectangle
128       instead.
129
130       inflate_ip(x, y)
131
132       Same as "<inflate"> above, but grows/shrinks the current Rect in place
133       and returns nothing.
134
135       clamp($rect)
136
137       Returns a new Rect moved to be completely inside the Rect object passed
138       as an argument. If the current Rect is too large to fit inside the
139       passed Rect, it is centered inside it, but its size is not changed.
140
141       clamp_ip($rect)
142
143       Same as "<clamp"> above, but moves the current Rect in place and
144       returns nothing.
145
146       clip($rect)
147
148       Returns a new Rect with the intersection between the two Rect objects,
149       that is, returns a new Rect cropped to be completely inside the Rect
150       object passed as an argument. If the two rectangles do not overlap to
151       begin with, a Rect with 0 size is returned, in the original Rect's
152       (x,y) coordinates.
153
154       clip_ip($rect)
155
156       Same as "<clip"> above, but crops the current Rect in place and returns
157       nothing. As the original method, the Rect becomes zero-sized if the two
158       rectangles do not overlap to begin with, retaining its (x, y)
159       coordinates.
160
161       union($rect)
162
163       Returns a new rectangle that completely covers the area of the current
164       Rect and the one passed as an argument. There may be area inside the
165       new Rect that is not covered by the originals.
166
167       union_ip($rect)
168
169       Same as "<union"> above, but resizes the current Rect in place and
170       returns nothing.
171
172       unionall( [$rect1, $rect2, ...] )
173
174       Returns the union of one rectangle with a sequence of many rectangles,
175       passed as an ARRAY REF.
176
177       unionall_ip( [$rect1, $rect2, ...] )
178
179       Same as "<unionall"> above, but resizes the current Rect in place and
180       returns nothing.
181
182       fit($rect)
183
184       Returns a new Rect moved and resized to fit the Rect object passed as
185       an argument. The aspect ratio of the original Rect is preserved, so the
186       new rectangle may be smaller than the target in either width or height.
187
188       fit_ip($rect)
189
190       Same as "<fit"> above, but moves/resizes the current Rect in place and
191       returns nothing.
192
193       normalize
194
195       Corrects negative sizes, flipping width/height of the Rect if they have
196       a negative size. No repositioning is made so the rectangle will remain
197       in the same place, but the negative sides will be swapped. This method
198       returns nothing.
199
200       contains($rect)
201
202       Returns true (non-zero) when the argument is completely inside the
203       Rect. Otherwise returns undef.
204
205       collidepoint(x, y)
206
207       Returns true (non-zero) if the given point is inside the Rect,
208       otherwise returns undef. A point along the right or bottom edge is not
209       considered to be inside the rectangle.
210
211       colliderect($rect)
212
213       Returns true (non-zero) if any portion of either rectangles overlap
214       (except for the top+bottom or left+right edges).
215
216       collidelist( [$rect1, $rect2, ...] )
217
218       Test whether the rectangle collides with any in a sequence of
219       rectangles, passed as an ARRAY REF. The index of the first collision
220       found is returned. Returns undef if no collisions are found.
221
222       collidelistall( [$rect1, $rect2, ...] )
223
224       Returns an ARRAY REF of all the indices that contain rectangles that
225       collide with the Rect. If no intersecting rectangles are found, an
226       empty list ref is returned.
227
228       collidehash( {key1 => $rect1, key2 => $rect2, ...} )
229
230       Receives a HASH REF and returns the a (key, value) list with the key
231       and value of the first hash item that collides with the Rect. If no
232       collisions are found, returns (undef, undef).
233
234       collidehashall( {key1 => $rect1, key2 => $rect2, ...} )
235
236       Returns a HASH REF of all the key and value pairs that intersect with
237       the Rect. If no collisions are found an empty hash ref is returned.
238

BUGS

240       Please report any bugs or feature requests to the bug tracker. I will
241       be notified, and then you'll automatically be notified of progress on
242       your bug as we make changes.
243

SUPPORT

245       You can find documentation for this module with the perldoc command.
246
247           perldoc SDLx::Rect
248

AUTHORS

250       See "AUTHORS" in SDL.
251

ACKNOWLEDGEMENTS

253       Many thanks to the authors of pygame.rect, in which this particular
254       module is heavily based.
255
257       This program is free software; you can redistribute it and/or modify it
258       under the same terms as Perl itself.
259

SEE ALSO

261       perl, SDL, SDL::Rect, SDL::Game
262
263
264
265perl v5.32.1                      2021-01-27                     SDLx::Rect(3)
Impressum