Mercurial > pygame
annotate src/surface.doc @ 1849:301bc61643a9 math_module
merged changes from trunk
| author | lorenz |
|---|---|
| date | Mon, 16 Nov 2009 18:31:40 +0000 |
| parents | 02c1e8e9c102 |
| children |
| rev | line source |
|---|---|
| 627 | 1 pygame.Surface |
| 2 pygame object for representing images | |
| 3 pygame.Surface((width, height), flags=0, depth=0, masks=None): return Surface | |
| 4 pygame.Surface((width, height), flags=0, Surface): return Surface | |
| 5 | |
| 6 A pygame Surface is used to represent any image. The Surface has a fixed | |
| 7 resolution and pixel format. Surfaces with 8bit pixels use a color palette | |
| 8 to map to 24bit color. | |
| 9 | |
| 10 Call pygame.Surface() to create a new image object. The Surface will be | |
| 11 cleared to all black. The only required arguments are the sizes. With no | |
| 12 additional arguments, the Surface will be created in a format that best | |
| 13 matches the display Surface. | |
| 14 | |
| 15 The pixel format can be controlled by passing the bit depth or an existing | |
| 16 Surface. The flags argument is a bitmask of additional features for the | |
| 17 surface. You can pass any combination of these flags: | |
| 18 | |
| 19 HWSURFACE, creates the image in video memory | |
| 20 SRCALPHA, the pixel format will include a per-pixel alpha | |
| 21 | |
| 22 Both flags are only a request, and may not be possible for all displays and | |
| 23 formats. | |
| 24 | |
| 25 Advance users can combine a set of bitmasks with a depth value. The masks | |
| 26 are a set of 4 integers representing which bits in a pixel will represent | |
| 27 each color. Normal Surfaces should not require the masks argument. | |
| 28 | |
| 29 Surfaces can have many extra attributes like alpha planes, colorkeys, source | |
| 30 rectangle clipping. These functions mainly effect how the Surface is blitted | |
| 1839 | 31 to other Surfaces. The blit routines will attempt to use hardware acceleration |
| 32 when possible, otherwise they will use highly optimized software blitting | |
| 33 methods. | |
| 627 | 34 |
| 35 There are three types of transparency supported in Pygame: colorkeys, | |
| 36 surface alphas, and pixel alphas. Surface alphas can be mixed with colorkeys, | |
| 37 but an image with per pixel alphas cannot use the other modes. Colorkey | |
| 38 transparency makes a single color value transparent. Any pixels matching | |
| 39 the colorkey will not be drawn. The surface alpha value is a single value | |
| 40 that changes the transparency for the entire image. A surface alpha of 255 | |
| 41 is opaque, and a value of 0 is completely transparent. | |
| 42 | |
| 43 Per pixel alphas are different because they store a transparency value for | |
| 44 every pixel. This allows for the most precise transparency effects, but it | |
| 45 also the slowest. Per pixel alphas cannot be mixed with surface alpha and | |
| 46 colorkeys. | |
| 47 | |
| 48 There is support for pixel access for the Surfaces. Pixel access on hardware | |
| 49 surfaces is slow and not recommended. Pixels can be accessed using the get_at() | |
| 50 and set_at() functions. These methods are fine for simple access, but will be | |
| 51 considerably slow when doing of pixel work with them. If you plan on doing a | |
| 52 lot of pixel level work, it is recommended to use the pygame.surfarray module, | |
| 53 which can treat the surfaces like large multidimensional arrays | |
| 54 (and it's quite quick). | |
| 55 | |
| 56 Any functions that directly access a surface's pixel data will need that | |
| 57 surface to be lock()'ed. These functions can lock() and unlock() the surfaces | |
| 58 themselves without assistance. But, if a function will be called many times, | |
| 59 there will be a lot of overhead for multiple locking and unlocking of the | |
| 60 surface. It is best to lock the surface manually before making the function | |
| 61 call many times, and then unlocking when you are finished. All functions that | |
| 62 need a locked surface will say so in their docs. Remember to leave the Surface | |
| 63 locked only while necessary. | |
| 64 | |
| 65 Surface pixels are stored internally as a single number that has all the | |
| 66 colors encoded into it. Use the Surface.map_rgb() and Surface.unmap_rgb() | |
| 67 to convert between individual red, green, and blue values into a packed | |
| 68 integer for that Surface. | |
| 69 | |
| 70 Surfaces can also reference sections of other Surfaces. These are created | |
| 71 with the Surface.subsurface() method. Any change to either Surface will | |
| 72 effect the other. | |
| 73 | |
| 74 Each Surface contains a clipping area. By default the clip area covers the | |
| 75 entire Surface. If it is changed, all drawing operations will only effect | |
| 76 the smaller area. | |
| 77 <SECTION> | |
| 78 | |
| 79 | |
| 80 | |
| 81 blit | |
| 82 draw one image onto another | |
|
685
fb4a41fce260
The start of some new blitting functions. add/sub/mult/min/max.
Rene Dudfield <renesd@gmail.com>
parents:
627
diff
changeset
|
83 Surface.blit(source, dest, area=None, special_flags = 0): return Rect |
| 627 | 84 |
| 85 Draws a source Surface onto this Surface. The draw can be positioned with | |
| 86 the dest argument. Dest can either be pair of coordinates representing the | |
| 87 upper left corner of the source. A Rect can also be passed as the destination | |
| 88 and the topleft corner of the rectangle will be used as the position for the | |
| 89 blit. The size of the destination rectangle does not effect the blit. | |
| 90 | |
| 91 An optional area rectangle can be passed as well. This represents a smaller | |
| 92 portion of the source Surface to draw. | |
| 93 | |
|
689
a84f4c96d12b
Some more changes to the blending stuff.
Rene Dudfield <renesd@gmail.com>
parents:
685
diff
changeset
|
94 An optional special flags is for passing in |
|
1141
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
95 new in 1.8.0: |
|
689
a84f4c96d12b
Some more changes to the blending stuff.
Rene Dudfield <renesd@gmail.com>
parents:
685
diff
changeset
|
96 BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAX |
|
1141
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
97 new in 1.8.1: |
|
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
98 BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX |
|
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
99 BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAX |
|
689
a84f4c96d12b
Some more changes to the blending stuff.
Rene Dudfield <renesd@gmail.com>
parents:
685
diff
changeset
|
100 With other special blitting flags perhaps added in the future. |
|
685
fb4a41fce260
The start of some new blitting functions. add/sub/mult/min/max.
Rene Dudfield <renesd@gmail.com>
parents:
627
diff
changeset
|
101 |
|
696
cc66586f274d
some changes from doc comments on website.
Rene Dudfield <renesd@gmail.com>
parents:
689
diff
changeset
|
102 The return rectangle is the area of the affected pixels, excluding any pixels |
| 627 | 103 outside the destination Surface, or outside the clipping area. |
| 104 | |
| 105 Pixel alphas will be ignored when blitting to an 8 bit Surface. | |
|
714
35ae39f336fd
Added some modifications based on comments written in the website.
Rene Dudfield <renesd@gmail.com>
parents:
696
diff
changeset
|
106 |
|
35ae39f336fd
Added some modifications based on comments written in the website.
Rene Dudfield <renesd@gmail.com>
parents:
696
diff
changeset
|
107 special_flags new in pygame 1.8. |
|
1524
28a601e11e62
fix surface self-blits for colorkey and blanket alpha: Bugzilla Bug 19
Lenard Lindstrom <len-l@telus.net>
parents:
1234
diff
changeset
|
108 |
|
28a601e11e62
fix surface self-blits for colorkey and blanket alpha: Bugzilla Bug 19
Lenard Lindstrom <len-l@telus.net>
parents:
1234
diff
changeset
|
109 For a surface with colorkey or blanket alpha, a blit to self may give slightly |
|
28a601e11e62
fix surface self-blits for colorkey and blanket alpha: Bugzilla Bug 19
Lenard Lindstrom <len-l@telus.net>
parents:
1234
diff
changeset
|
110 different colors than a non self-blit. |
| 627 | 111 <END> |
| 112 | |
| 113 | |
|
685
fb4a41fce260
The start of some new blitting functions. add/sub/mult/min/max.
Rene Dudfield <renesd@gmail.com>
parents:
627
diff
changeset
|
114 |
| 627 | 115 convert |
| 116 change the pixel format of an image | |
| 117 Surface.convert(Surface): return Surface | |
| 118 Surface.convert(depth, flags=0): return Surface | |
|
745
a807e78efb40
Removed "Surface.convert(depth, masks): return Surface"
Rene Dudfield <renesd@gmail.com>
parents:
744
diff
changeset
|
119 Surface.convert(masks, flags=0): return Surface |
| 627 | 120 Surface.convert(): return Surface |
| 121 | |
| 122 Creates a new copy of the Surface with the pixel format changed. The new pixel | |
| 123 format can be determined from another existing Surface. Otherwise depth, | |
| 124 flags, and masks arguments can be used, similar to the pygame.Surface() call. | |
| 125 | |
| 126 If no arguments are passed the new Surface will have the same pixel format | |
| 127 as the display Surface. This is always the fastest format for blitting. It | |
| 128 is a good idea to convert all Surfaces before they are blitted many times. | |
| 129 | |
| 130 The converted Surface will have no pixel alphas. They will be stripped if | |
| 131 the original had them. See Surface.convert_alpha() for preserving or creating | |
| 132 per-pixel alphas. | |
| 133 <END> | |
| 134 | |
| 135 | |
| 136 | |
| 137 convert_alpha | |
| 138 change the pixel format of an image including per pixel alphas | |
| 139 Surface.convert_alpha(Surface): return Surface | |
| 140 Surface.convert_alpha(): return Surface | |
| 141 | |
| 142 Creates a new copy of the surface with the desired pixel format. The new | |
| 143 surface will be in a format suited for quick blitting to the given format | |
| 144 with per pixel alpha. If no surface is given, the new surface will be | |
|
1038
2fab82895a31
Fixed numerous doc comments. Removed wrong Rect.clip_ip() entry.
marcus
parents:
1022
diff
changeset
|
145 optimized for blitting to the current display. |
| 627 | 146 |
| 147 Unlike the Surface.convert() method, the pixel format for the new image will not | |
| 148 be exactly the same as the requested source, but it will be optimized for | |
| 149 fast alpha blitting to the destination. | |
| 150 <END> | |
| 151 | |
| 152 | |
| 153 | |
| 154 copy | |
| 155 create a new copy of a Surface | |
| 156 Surface.copy(): return Surface | |
| 157 | |
| 158 Makes a duplicate copy of a Surface. The new Surface will have the same | |
| 159 pixel formats, color palettes, and transparency settings as the original. | |
| 160 <END> | |
| 161 | |
| 162 | |
| 163 | |
| 164 fill | |
| 165 fill Surface with a solid color | |
|
819
f10c63453e4e
Marcus has added in blend modes for the surface.fill function.
Rene Dudfield <renesd@gmail.com>
parents:
745
diff
changeset
|
166 Surface.fill(color, rect=None, special_flags=0): return Rect |
| 627 | 167 |
| 168 Fill the Surface with a solid color. If no rect argument is given the | |
| 169 entire Surface will be filled. The rect argument will limit the fill to | |
| 170 a specific area. The fill will also be contained by the Surface clip area. | |
| 171 | |
|
845
c420a3e23f74
Changed the docs for surface.fill for SRCALPHA surfaces.
Rene Dudfield <renesd@gmail.com>
parents:
819
diff
changeset
|
172 The color argument can be either a RGB sequence, a RGBA sequence or |
|
c420a3e23f74
Changed the docs for surface.fill for SRCALPHA surfaces.
Rene Dudfield <renesd@gmail.com>
parents:
819
diff
changeset
|
173 a mapped color index. If using RGBA, the Alpha (A part of RGBA) is ignored |
|
c420a3e23f74
Changed the docs for surface.fill for SRCALPHA surfaces.
Rene Dudfield <renesd@gmail.com>
parents:
819
diff
changeset
|
174 unless the surface uses per pixel alpha (Surface has the SRCALPHA flag). |
| 627 | 175 |
|
819
f10c63453e4e
Marcus has added in blend modes for the surface.fill function.
Rene Dudfield <renesd@gmail.com>
parents:
745
diff
changeset
|
176 An optional special_flags is for passing in |
|
1141
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
177 new in 1.8.0: |
|
819
f10c63453e4e
Marcus has added in blend modes for the surface.fill function.
Rene Dudfield <renesd@gmail.com>
parents:
745
diff
changeset
|
178 BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAX |
|
1141
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
179 new in 1.8.1: |
|
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
180 BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX |
|
99a96e8e563d
Added BLEND_RGBA_* special flags for blit, and fill.
Rene Dudfield <renesd@gmail.com>
parents:
1137
diff
changeset
|
181 BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAX |
|
819
f10c63453e4e
Marcus has added in blend modes for the surface.fill function.
Rene Dudfield <renesd@gmail.com>
parents:
745
diff
changeset
|
182 With other special blitting flags perhaps added in the future. |
|
f10c63453e4e
Marcus has added in blend modes for the surface.fill function.
Rene Dudfield <renesd@gmail.com>
parents:
745
diff
changeset
|
183 |
|
696
cc66586f274d
some changes from doc comments on website.
Rene Dudfield <renesd@gmail.com>
parents:
689
diff
changeset
|
184 This will return the affected Surface area. |
| 627 | 185 <END> |
| 186 | |
| 187 | |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
188 |
|
1525
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
189 scroll |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
190 Shift the surface image in place |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
191 Surface.scroll(dx=0, dy=0): return None |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
192 |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
193 Move the image by dx pixels right and dy pixels down. dx and dy may be negative |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
194 for left and up scrolls respectively. Areas of the surface that are not |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
195 overwritten retain their original pixel values. Scrolling is contained |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
196 by the Surface clip area. It is safe to have dx and dy values that exceed |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
197 the surface size. |
| 1849 | 198 |
| 199 New in Pygame 1.9 | |
|
1525
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
200 <END> |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
201 |
|
48ab3db38416
add Surface.scroll method
Lenard Lindstrom <len-l@telus.net>
parents:
1524
diff
changeset
|
202 |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
203 |
| 627 | 204 set_colorkey |
| 205 Set the transparent colorkey | |
| 206 Surface.set_colorkey(Color, flags=0): return None | |
| 207 Surface.set_colorkey(None): return None | |
| 208 | |
| 209 Set the current color key for the Surface. When blitting this Surface onto | |
| 210 a destination, and pixels that have the same color as the colorkey will be | |
| 211 transparent. The color can be an RGB color or a mapped color integer. If None | |
| 212 is passed, the colorkey will be unset. | |
| 213 | |
| 214 The colorkey will be ignored if the Surface is formatted to use per pixel | |
| 215 alpha values. The colorkey can be mixed with the full Surface alpha value. | |
| 216 | |
| 217 The optional flags argument can be set to pygame.RLEACCEL to provide better | |
| 218 performance on non accelerated displays. An RLEACCEL Surface will be slower | |
| 219 to modify, but quicker to blit as a source. | |
| 220 <END> | |
| 221 | |
| 222 | |
| 223 | |
| 224 get_colorkey | |
| 225 Get the current transparent colorkey | |
| 226 Surface.get_colorkey(): return RGB or None | |
| 227 | |
| 228 Return the current colorkey value for the Surface. If the colorkey is not | |
| 229 set then None is returned. | |
| 230 <END> | |
| 231 | |
| 232 | |
| 233 | |
| 234 set_alpha | |
| 235 set the alpha value for the full Surface image | |
| 236 Surface.set_alpha(value, flags=0): return None | |
| 237 Surface.set_alpha(None): return None | |
| 238 | |
| 239 Set the current alpha value fo r the Surface. When blitting this Surface onto | |
| 240 a destination, the pixels will be drawn slightly transparent. The alpha value | |
| 241 is an integer from 0 to 255, 0 is fully transparent and 255 is fully | |
| 242 opaque. If None is passed for the alpha value, then the Surface alpha will | |
| 243 be disabled. | |
| 244 | |
| 245 This value is different than the per pixel Surface alpha. If the Surface | |
| 246 format contains per pixel alphas, then this alpha value will be ignored. | |
| 247 If the Surface contains per pixel alphas, setting the alpha value to None | |
| 248 will disable the per pixel transparency. | |
| 249 | |
| 250 The optional flags argument can be set to pygame.RLEACCEL to provide better | |
| 251 performance on non accelerated displays. An RLEACCEL Surface will be slower | |
| 252 to modify, but quicker to blit as a source. | |
| 253 <END> | |
| 254 | |
| 255 | |
| 256 | |
| 257 get_alpha | |
| 258 get the current Surface transparency value | |
| 259 Surface.get_alpha(): return int_value or None | |
| 260 | |
| 261 Return the current alpha value for the Surface. If the alpha value is not | |
| 262 set then None is returned. | |
| 263 <END> | |
| 264 | |
| 265 | |
| 266 | |
| 267 lock | |
| 268 lock the Surface memory for pixel access | |
| 269 Surface.lock(): return None | |
| 270 | |
| 271 Lock the pixel data of a Surface for access. On accelerated Surfaces, the | |
| 272 pixel data may be stored in volatile video memory or nonlinear compressed | |
| 273 forms. When a Surface is locked the pixel memory becomes available to access | |
| 274 by regular software. Code that reads or writes pixel values will need the | |
| 275 Surface to be locked. | |
| 276 | |
| 277 Surfaces should not remain locked for more than necessary. A locked Surface | |
| 278 can often not be displayed or managed by Pygame. | |
| 279 | |
| 280 Not all Surfaces require locking. The Surface.mustlock() method can determine | |
| 281 if it is actually required. There is no performance penalty for locking and | |
| 282 unlocking a Surface that does not need it. | |
| 283 | |
| 284 All pygame functions will automatically lock and unlock the Surface data as | |
| 285 needed. If a section of code is going to make calls that will repeatedly | |
| 286 lock and unlock the Surface many times, it can be helpful to wrap the block | |
| 287 inside a lock and unlock pair. | |
| 288 | |
| 289 It is safe to nest locking and unlocking calls. The surface will only be | |
| 290 unlocked after the final lock is released. | |
| 291 <END> | |
| 292 | |
| 293 | |
| 294 | |
| 295 unlock | |
| 296 unlock the Surface memory from pixel access | |
| 297 Surface.unlock(): return None | |
| 298 | |
| 299 Unlock the Surface pixel data after it has been locked. The unlocked Surface | |
| 300 can once again be drawn and managed by Pygame. See the Surface.lock() | |
| 301 documentation for more details. | |
| 302 | |
| 303 All pygame functions will automatically lock and unlock the Surface data as | |
| 304 needed. If a section of code is going to make calls that will repeatedly | |
| 305 lock and unlock the Surface many times, it can be helpful to wrap the block | |
| 306 inside a lock and unlock pair. | |
| 307 | |
| 308 It is safe to nest locking and unlocking calls. The surface will only be | |
| 309 unlocked after the final lock is released. | |
| 310 <END> | |
| 311 | |
| 312 | |
| 313 | |
| 314 mustlock | |
| 315 test if the Surface requires locking | |
| 316 Surface.mustlock(): return bool | |
| 317 | |
| 318 Returns True if the Surface is required to be locked to access pixel data. | |
| 319 Usually pure software Surfaces do not require locking. This method is | |
| 320 rarely needed, since it is safe and quickest to just lock all Surfaces as | |
| 321 needed. | |
| 322 | |
| 323 All pygame functions will automatically lock and unlock the Surface data as | |
| 324 needed. If a section of code is going to make calls that will repeatedly | |
| 325 lock and unlock the Surface many times, it can be helpful to wrap the block | |
| 326 inside a lock and unlock pair. | |
| 327 <END> | |
| 328 | |
| 329 | |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
330 |
| 627 | 331 get_locked |
| 332 test if the Surface is current locked | |
| 333 Surface.get_locked(): return bool | |
| 334 | |
| 335 Returns True when the Surface is locked. It doesn't matter how many times | |
|
1137
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
336 the Surface is locked. |
|
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
337 <END> |
|
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
338 |
|
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
339 |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
340 |
|
1137
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
341 get_locks |
|
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
342 Gets the locks for the Surface |
|
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
343 Surface.get_locks(): return tuple |
|
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
344 |
|
ec3ced33488f
Reworked locking code to be more strict about locking.
marcus
parents:
1038
diff
changeset
|
345 Returns the currently existing locks for the Surface. |
| 627 | 346 <END> |
| 347 | |
| 348 | |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
349 |
| 627 | 350 get_at |
| 351 get the color value at a single pixel | |
| 352 Surface.get_at((x, y)): return Color | |
| 353 | |
| 1839 | 354 Return a copy of the RGBA Color value at the given pixel. If the Surface has |
| 355 no per pixel alpha, then the alpha value will always be 255 (opaque). | |
| 356 If the pixel position is outside the area of the Surface an IndexError | |
| 357 exception will be raised. | |
| 627 | 358 |
| 359 Getting and setting pixels one at a time is generally too slow to be used | |
| 1839 | 360 in a game or realtime situation. It is better to use methods which operate |
| 361 on many pixels at a time like with the blit, fill and draw methods - | |
| 362 or by using surfarray/PixelArray. | |
| 627 | 363 |
| 364 This function will temporarily lock and unlock the Surface as needed. | |
| 1839 | 365 |
| 366 Returning a Color instead of tuple, New in pygame 1.9.0. | |
| 367 Use tuple(surf.get_at((x,y))) if you want a tuple, and not a Color. | |
| 368 This should only matter if you want to use the color as a key in a dict. | |
| 627 | 369 <END> |
| 370 | |
| 371 | |
| 372 | |
| 373 set_at | |
| 374 set the color value for a single pixel | |
| 375 Surface.set_at((x, y), Color): return None | |
| 376 | |
| 377 Set the RGBA or mapped integer color value for a single pixel. If the Surface | |
| 378 does not have per pixel alphas, the alpha value is ignored. Settting pixels | |
| 379 outside the Surface area or outside the Surface clipping will have no effect. | |
| 380 | |
| 381 Getting and setting pixels one at a time is generally too slow to be used | |
| 382 in a game or realtime situation. | |
| 383 | |
| 384 This function will temporarily lock and unlock the Surface as needed. | |
| 385 <END> | |
| 386 | |
| 387 | |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
388 |
| 627 | 389 get_palette |
| 390 get the color index palette for an 8bit Surface | |
| 391 Surface.get_palette(): return [RGB, RGB, RGB, ...] | |
| 392 | |
| 393 Return a list of up to 256 color elements that represent the indexed colors | |
| 394 used in an 8bit Surface. The returned list is a copy of the palette, and | |
| 395 changes will have no effect on the Surface. | |
| 1839 | 396 |
| 397 Returning a list of Color(with length 3) instances instead of tuples, New in pygame 1.9.0 | |
| 627 | 398 <END> |
| 399 | |
| 400 | |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
401 |
| 627 | 402 get_palette_at |
| 403 get the color for a single entry in a palette | |
| 404 Surface.get_palette_at(index): return RGB | |
| 405 | |
| 406 Returns the red, green, and blue color values for a single index in a Surface | |
| 407 palette. The index should be a value from 0 to 255. | |
| 1839 | 408 |
| 409 Returning Color(with length 3) instance instead of a tuple, New in pygame 1.9.0 | |
| 627 | 410 <END> |
| 411 | |
| 412 | |
| 413 | |
| 414 set_palette | |
| 415 set the color palette for an 8bit Surface | |
| 416 Surface.set_palette([RGB, RGB, RGB, ...]): return None | |
| 417 | |
| 418 Set the full palette for an 8bit Surface. This will replace the colors in | |
| 419 the existing palette. A partial palette can be passed and only the first | |
| 420 colors in the original palette will be changed. | |
| 421 | |
| 422 This function has no effect on a Surface with more than 8bits per pixel. | |
| 423 <END> | |
| 424 | |
| 425 | |
| 426 | |
| 427 set_palette_at | |
| 428 set the color for a single index in an 8bit Surface palette | |
| 429 Surface.set_at(index, RGB): return None | |
| 430 | |
| 431 Set the palette value for a single entry in a Surface palette. The index should | |
| 432 be a value from 0 to 255. | |
| 433 | |
| 434 This function has no effect on a Surface with more than 8bits per pixel. | |
| 435 <END> | |
| 436 | |
| 437 | |
| 438 | |
| 439 map_rgb | |
| 440 convert a color into a mapped color value | |
| 441 Surface.map_rgb(Color): return mapped_int | |
| 442 | |
| 443 Convert an RGBA color into the mapped integer value for this Surface. The | |
| 444 returned integer will contain no more bits than the bit depth of the Surface. | |
| 445 Mapped color values are not often used inside Pygame, but can be passed to | |
| 446 most functions that require a Surface and a color. | |
| 447 | |
| 448 See the Surface object documentation for more information about colors | |
| 449 and pixel formats. | |
| 450 <END> | |
| 451 | |
| 452 | |
| 453 | |
| 454 unmap_rgb | |
| 455 convert a mapped integer color value into a Color | |
| 456 Surface.map_rgb(mapped_int): return Color | |
| 457 | |
| 458 Convert an mapped integer color into the RGB color components for this Surface. | |
| 459 Mapped color values are not often used inside Pygame, but can be passed to | |
| 460 most functions that require a Surface and a color. | |
| 461 | |
| 462 See the Surface object documentation for more information about colors | |
| 463 and pixel formats. | |
| 464 <END> | |
| 465 | |
| 466 | |
| 467 | |
| 468 set_clip | |
| 469 set the current clipping area of the Surface | |
| 470 Surface.set_clip(rect): return None | |
| 471 Surface.set_clip(None): return None | |
| 472 | |
| 473 Each Surface has an active clipping area. This is a rectangle that represents | |
| 474 the only pixels on the Surface that can be modified. If None is passed for the | |
| 475 rectangle the full Surface will be available for changes. | |
| 476 | |
| 477 The clipping area is always restricted to the area of the Surface itself. If | |
| 478 the clip rectangle is too large it will be shrunk to fit inside the Surface. | |
| 479 <END> | |
| 480 | |
| 481 | |
| 482 | |
| 483 get_clip | |
| 1022 | 484 get the current clipping area of the Surface |
| 627 | 485 Surface.get_clip(): return Rect |
| 486 | |
| 487 Return a rectangle of the current clipping area. The Surface will always | |
| 488 return a valid rectangle that will never be outside the bounds of the image. | |
| 489 If the Surface has had None set for the clipping area, the Surface will | |
| 490 return a rectangle with the full area of the Surface. | |
| 491 <END> | |
| 492 | |
| 493 | |
| 494 | |
| 495 subsurface | |
| 496 create a new surface that references its parent | |
| 497 Surface.subsurface(Rect): return Surface | |
| 498 | |
| 499 Returns a new Surface that shares its pixels with its new parent. The new | |
| 500 Surface is considered a child of the original. Modifications to either | |
| 501 Surface pixels will effect each other. Surface information like clipping | |
| 502 area and color keys are unique to each Surface. | |
| 503 | |
| 504 The new Surface will inherit the palette, color key, and alpha settings from | |
| 505 its parent. | |
| 506 | |
| 507 It is possible to have any number of subsurfaces and subsubsurfaces on the | |
| 508 parent. It is also possible to subsurface the display Surface if the display | |
| 509 mode is not hardware accelerated. | |
| 510 | |
| 511 See the Surface.get_offset(), Surface.get_parent() to learn more | |
| 512 about the state of a subsurface. | |
| 513 <END> | |
| 514 | |
| 515 | |
| 516 | |
| 517 get_parent | |
| 518 find the parent of a subsurface | |
| 519 Surface.get_parent(): return Surface | |
| 520 | |
| 521 Returns the parent Surface of a subsurface. If this is not a subsurface | |
| 522 then None will be returned. | |
| 523 <END> | |
| 524 | |
| 525 | |
| 526 | |
| 527 get_abs_parent | |
| 528 find the top level parent of a subsurface | |
| 529 Surface.get_abs_parent(): return Surface | |
| 530 | |
| 531 Returns the parent Surface of a subsurface. If this is not a subsurface | |
|
744
e0e6e8a457db
get_abs_parent was wrong about None being returned.
Rene Dudfield <renesd@gmail.com>
parents:
730
diff
changeset
|
532 then this surface will be returned. |
| 627 | 533 <END> |
| 534 | |
| 535 | |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
536 |
| 627 | 537 get_offset |
| 538 find the position of a child subsurface inside a parent | |
| 539 Surface.get_offset(): return (x, y) | |
| 540 | |
| 541 Get the offset position of a child subsurface inside of a parent. If the | |
| 542 Surface is not a subsurface this will return (0, 0). | |
| 543 <END> | |
| 544 | |
| 545 | |
| 546 | |
| 547 get_abs_offset | |
| 548 find the absolute position of a child subsurface inside its top level parent | |
| 549 Surface.get_abs_offset(): return (x, y) | |
| 550 | |
| 551 Get the offset position of a child subsurface inside of its top level | |
| 552 parent Surface. If the Surface is not a subsurface this will return (0, 0). | |
| 553 <END> | |
| 554 | |
| 555 | |
| 556 | |
| 557 get_size | |
| 558 get the dimensions of the Surface | |
| 559 Surface.get_size(): return (width, height) | |
| 560 | |
| 561 Return the width and height of the Surface in pixels. | |
| 562 <END> | |
| 563 | |
| 564 | |
| 565 | |
| 566 get_width | |
| 567 get the width of the Surface | |
| 568 Surface.get_width(): return width | |
| 569 | |
| 570 Return the width of the Surface in pixels. | |
| 571 <END> | |
| 572 | |
| 573 | |
| 574 | |
| 575 get_height | |
| 576 get the height of the Surface | |
| 577 Surface.get_height(): return height | |
| 578 | |
| 579 Return the height of the Surface in pixels. | |
| 580 <END> | |
| 581 | |
| 582 | |
| 583 | |
| 584 get_rect | |
| 585 get the rectangular area of the Surface | |
| 586 Surface.get_rect(**kwargs): return Rect | |
| 587 | |
| 588 Returns a new rectangle covering the entire surface. This rectangle will | |
| 589 always start at 0, 0 with a width. and height the same size as the image. | |
| 590 | |
| 591 You can pass keyword argument values to this function. These named values | |
| 592 will be applied to the attributes of the Rect before it is returned. An | |
| 593 example would be 'mysurf.get_rect(center=(100,100))' to create a rectangle | |
| 594 for the Surface centered at a given position. | |
| 595 <END> | |
| 596 | |
| 597 | |
| 598 | |
| 599 get_bitsize | |
| 600 get the bit depth of the Surface pixel format | |
| 601 Surface.get_bitsize(): return int | |
| 602 | |
| 603 Returns the number of bits used to represent each pixel. This value may not | |
| 604 exactly fill the number of bytes used per pixel. For example a 15 bit Surface | |
| 605 still requires a full 2 bytes. | |
| 606 <END> | |
| 607 | |
| 608 | |
| 609 | |
| 610 get_bytesize | |
| 611 get the bytes used per Surface pixel | |
| 612 Surface.get_bytesize(): return int | |
| 613 | |
| 614 Return the number of bytes used per pixel. | |
| 615 <END> | |
| 616 | |
| 617 | |
| 618 | |
| 619 get_flags | |
| 620 get the additional flags used for the Surface | |
| 621 Surface.get_flags(): return int | |
| 622 | |
| 623 Returns a set of current Surface features. Each feature is a bit in the | |
|
729
3a0ffb0d17bc
added a full list of flags into the surface docs
Rene Dudfield <renesd@gmail.com>
parents:
714
diff
changeset
|
624 flags bitmask. Typical flags are HWSURFACE, RLEACCEL, SRCALPHA, and SRCCOLORKEY. |
|
3a0ffb0d17bc
added a full list of flags into the surface docs
Rene Dudfield <renesd@gmail.com>
parents:
714
diff
changeset
|
625 |
|
3a0ffb0d17bc
added a full list of flags into the surface docs
Rene Dudfield <renesd@gmail.com>
parents:
714
diff
changeset
|
626 |
|
730
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
627 Here is a more complete list of flags. A full list can be found in SDL_video.h |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
628 SWSURFACE 0x00000000 # Surface is in system memory |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
629 HWSURFACE 0x00000001 # Surface is in video memory |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
630 ASYNCBLIT 0x00000004 # Use asynchronous blits if possible |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
631 |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
632 Available for pygame.display.set_mode() |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
633 ANYFORMAT 0x10000000 # Allow any video depth/pixel-format |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
634 HWPALETTE 0x20000000 # Surface has exclusive palette |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
635 DOUBLEBUF 0x40000000 # Set up double-buffered video mode |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
636 FULLSCREEN 0x80000000 # Surface is a full screen display |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
637 OPENGL 0x00000002 # Create an OpenGL rendering context |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
638 OPENGLBLIT 0x0000000A # Create an OpenGL rendering context |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
639 # and use it for blitting. Obsolete. |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
640 RESIZABLE 0x00000010 # This video mode may be resized |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
641 NOFRAME 0x00000020 # No window caption or edge frame |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
642 |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
643 Used internally (read-only) |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
644 HWACCEL 0x00000100 # Blit uses hardware acceleration |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
645 SRCCOLORKEY 0x00001000 # Blit uses a source color key |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
646 RLEACCELOK 0x00002000 # Private flag |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
647 RLEACCEL 0x00004000 # Surface is RLE encoded |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
648 SRCALPHA 0x00010000 # Blit uses source alpha blending |
|
e2296f088920
moved the full list of flags to the get_flags call where it would be needed the most.
Rene Dudfield <renesd@gmail.com>
parents:
729
diff
changeset
|
649 PREALLOC 0x01000000 # Surface uses preallocated memory |
| 627 | 650 <END> |
| 651 | |
| 652 | |
| 653 | |
| 654 get_pitch | |
| 655 get the number of bytes used per Surface row | |
| 656 Surface.get_pitch(): return int | |
| 657 | |
| 658 Return the number of bytes separating each row in the Surface. Surfaces | |
| 659 in video memory are not always linearly packed. Subsurfaces will also have a | |
| 660 larger pitch than their real width. | |
| 661 | |
| 662 This value is not needed for normal Pygame usage. | |
| 663 <END> | |
| 664 | |
| 665 | |
| 666 | |
| 667 get_masks | |
| 668 the bitmasks needed to convert between a color and a mapped integer | |
| 669 Surface.get_masks(): return (R, G, B, A) | |
| 670 | |
| 671 Returns the bitmasks used to isolate each color in a mapped integer. | |
| 672 | |
| 673 This value is not needed for normal Pygame usage. | |
| 674 <END> | |
| 675 | |
| 676 | |
| 677 | |
|
1234
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
678 set_masks |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
679 set the bitmasks needed to convert between a color and a mapped integer |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
680 Surface.set_masks((r,g,b,a)): return None |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
681 |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
682 This is not needed for normal Pygame usage. |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
683 New in pygame 1.8.1 |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
684 <END> |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
685 |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
686 |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
687 |
| 627 | 688 get_shifts |
| 689 the bit shifts needed to convert between a color and a mapped integer | |
| 690 Surface.get_shifts(): return (R, G, B, A) | |
| 691 | |
| 692 Returns the pixel shifts need to convert between each color and a mapped | |
| 693 integer. | |
| 694 | |
| 695 This value is not needed for normal Pygame usage. | |
| 696 <END> | |
| 697 | |
| 698 | |
| 699 | |
|
1234
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
700 set_shifts |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
701 sets the bit shifts needed to convert between a color and a mapped integer |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
702 Surface.get_shifts((r,g,b,a)): return None |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
703 |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
704 This is not needed for normal Pygame usage. |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
705 New in pygame 1.8.1 |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
706 <END> |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
707 |
|
2ad2aa11e514
Added Surface.set_masks and .set_shifts useful for using data in
Rene Dudfield <renesd@gmail.com>
parents:
1141
diff
changeset
|
708 |
|
1625
a8e159731135
fixing up spacing between functions
Rene Dudfield <renesd@gmail.com>
parents:
1525
diff
changeset
|
709 |
| 627 | 710 get_losses |
| 711 the significant bits used to convert between a color and a mapped integer | |
| 712 Surface.get_losses(): return (R, G, B, A) | |
| 713 | |
| 930 | 714 Return the least significant number of bits stripped from each color |
| 627 | 715 in a mapped integer. |
| 716 | |
| 717 This value is not needed for normal Pygame usage. | |
| 718 <END> | |
| 860 | 719 |
| 930 | 720 |
| 721 | |
| 722 get_bounding_rect | |
| 723 find the smallest rect containing data | |
| 724 Surface.get_bounding_rect(min_alpha = 1): return Rect | |
| 725 | |
| 726 Returns the smallest rectangular region that contains all the pixels | |
| 727 in the surface that have an alpha value greater than or equal to the | |
| 728 minimum alpha value. | |
| 729 | |
| 730 This function will temporarily lock and unlock the Surface as needed. | |
| 934 | 731 |
| 732 New in pygame 1.8. | |
| 930 | 733 <END> |
| 734 | |
| 735 | |
| 736 | |
| 860 | 737 get_buffer |
| 738 acquires a buffer object for the pixels of the Surface. | |
| 739 Surface.get_buffer(): return BufferProxy | |
| 740 | |
| 741 Return a buffer object for the pixels of the Surface. The buffer can be | |
| 742 used for direct pixel access and manipulation. | |
| 743 | |
| 744 This method implicitly locks the Surface. The lock will be released, | |
| 745 once the returned BufferProxy object is deleted. | |
| 746 | |
| 747 New in pygame 1.8. | |
| 627 | 748 <END> |
| 860 | 749 <END> |