1SDLx::Rect(3) User Contributed Perl Documentation SDLx::Rect(3)
2
6 SDLx::Rect - SDL extension for storing and manipulating rectangular
7 coordinates
8
10 Extension
11
13 SDLx::Rect works as a SDL::Rect in the lower layer (SDL::*) but
14 provides more methods to users.
15 use SDLx::Rect; #instead of SDL::Rect
17 my $rect = SDLx::Rect->new( $x, $y, $w, $h); #same as SDL::Rect
19 ...
21 SDL::Video::fill_rect( .. , $rect, ...); # use like SDL::Rect
23
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 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 ATTRIBUTES
39 All Rect attributes are accessors, meaning you can get them by name,
40 and set them by passing a value:
41 $rect->left(15);
43 $rect->left; # 15
44 The Rect object has several attributes which can be used to resize,
46 move and align the Rect.
47 • width, w - gets/sets object's width
49 • height, h - gets/sets object's height
51 • left, x - moves the object left position to match the given
53 coordinate
54 • top, y - moves the object top position to match the given
56 coordinate
57 • bottom - moves the object bottom position to match the given
59 coordinate
60 • right - moves the object right position to match the given
62 coordinate
63 • centerx - moves the object's horizontal center to match the given
65 coordinate
66 • centery - moves the object's vertical center to match the given
68 coordinate
69 Some of the attributes above can be fetched or set in pairs:
71 $rect->topleft(10, 15); # top is now 10, left is now 15
73 my ($width, $height) = $rect->size;
75 • size - gets/sets object's size (width, height)
77 • topleft - gets/sets object's top and left positions
79 • midleft - gets/sets object's vertical center and left positions
81 • bottomleft - gets/sets object's bottom and left positions
83 • center - gets/sets object's center (horizontal(x), vertical(y))
85 • topright - gets/sets object's top and right positions
87 • midright - gets/sets object's vertical center and right positions
89 • bottomright - gets/sets object's bottom and right positions
91 • midtop - gets/sets object's horizontal center and top positions
93 • midbottom - gets/sets object's horizontal center and bottom
95 positions
96 METHODS
98 Methods denoted as receiving Rect objects can receive either
99 "<SDLx::Rect"> or raw "<SDL::Rect"> objects.
100 new ($left, $top, $width, $height)
102 Returns a new Rect object with the given coordinates. If any value is
104 omitted (by passing undef), 0 is used instead.
105 copy
107 duplicate
109 Returns a new Rect object having the same position and size as the
111 original
112 move(x, y)
114 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 move_ip(x, y)
119 Same as "<move"> above, but moves the current Rect in place and returns
121 nothing.
122 inflate(x, y)
124 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 inflate_ip(x, y)
131 Same as "<inflate"> above, but grows/shrinks the current Rect in place
133 and returns nothing.
134 clamp($rect)
136 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 clamp_ip($rect)
142 Same as "<clamp"> above, but moves the current Rect in place and
144 returns nothing.
145 clip($rect)
147 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 clip_ip($rect)
155 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 union($rect)
162 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 union_ip($rect)
168 Same as "<union"> above, but resizes the current Rect in place and
170 returns nothing.
171 unionall( [$rect1, $rect2, ...] )
173 Returns the union of one rectangle with a sequence of many rectangles,
175 passed as an ARRAY REF.
176 unionall_ip( [$rect1, $rect2, ...] )
178 Same as "<unionall"> above, but resizes the current Rect in place and
180 returns nothing.
181 fit($rect)
183 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 fit_ip($rect)
189 Same as "<fit"> above, but moves/resizes the current Rect in place and
191 returns nothing.
192 normalize
194 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 contains($rect)
201 Returns true (non-zero) when the argument is completely inside the
203 Rect. Otherwise returns undef.
204 collidepoint(x, y)
206 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 colliderect($rect)
212 Returns true (non-zero) if any portion of either rectangles overlap
214 (except for the top+bottom or left+right edges).
215 collidelist( [$rect1, $rect2, ...] )
217 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 collidelistall( [$rect1, $rect2, ...] )
223 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 collidehash( {key1 => $rect1, key2 => $rect2, ...} )
229 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 collidehashall( {key1 => $rect1, key2 => $rect2, ...} )
235 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
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
245 You can find documentation for this module with the perldoc command.
246 perldoc SDLx::Rect
248
250 See "AUTHORS" in SDL.
251
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
261 perl, SDL, SDL::Rect, SDL::Game
262perl v5.36.0 2023-03-10 SDLx::Rect(3)