Mercurial > pygame

annotate src/pixelarray.doc @ 989:1bbdc02af359

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
author marcus
date Fri, 04 Apr 2008 08:04:49 +0000
parents 2c37905a2091
children 404e3a0be4f8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
1 pygame.PixelArray
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
2 pygame Object for direct pixel access of surfaces
873
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
3 pygame.PixelArray(Surface): return PixelArray
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
4
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
5 The PixelArray wraps up a Surface and provides a direct 2D array access
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
6 to its pixels using the surface its rows as first and its columns as
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
7 second axis. It supports slicing, row and pixel manipluation, slicing
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
8 and slice assignments while inplace operations such as addition,
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
9 subtraction, multiplication, division and so forth are not allowed.
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
10
873
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
11 While it is possible to assign both, integer color values and RGB(A)
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
12 color tuples, the PixelArray will only use integers for the color
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
13 representation. Thus, checking for certain colors has to be done using
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
14 the Surface.map_rgb() method of the surface, the PixelArray was created
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
15 for.
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
16
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
17 pxarray = pygame.PixelArray (surface)
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
18 # Check, if the first pixel at the topleft corner is blue
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
19 if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
20 ...
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
21
877
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
22 Pixels can be manipulated using integer values or color tuples.
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
23
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
24 pxarray[x][y] = 0xFF00FF
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
25 pxarray[x][y] = (255, 0, 255)
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
26
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
27 If you operate on a slice, you also can use arbitrary sequences or other
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
28 PixelArray objects to modify the pixels. They have to match the size of
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
29 the PixelArray however.
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
30
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
31 pxarray[a:b] = 0xFF00FF # set all pixels to 0xFF00FF
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
32
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
33 pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
34 # second pixel = 0xAACCEE, ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
35 pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # same as above
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
36 pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...) # same as above
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
37
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
38 pxarray[a:b] = otherarray[x:y] # slice sizes must match
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
39
877
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
40 Note, that something like
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
41
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
42 pxarray[2:4][3:5] = ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
43
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
44 will not cause a rectangular manipulation. Instead it will be first
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
45 sliced to a two-column array, which then shall be sliced by columns once
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
46 more, which will fail due an IndexError. This is caused by the slicing
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
47 mechanisms in python and an absolutely correct behaviour.
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
48 Create a single columned slice first, which you can manipulate then:
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
49
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
50 pxarray[2][3:5] = ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
51 pxarray[3][3:5] = ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
52
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
53 If you want to make a rectangular manipulation or create a view of a
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
54 part of the PixelArray, you also can use the subscript abilities. You
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
55 can easily create different view by creating 'subarrays' using the
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
56 subscripts.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
57
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
58 # Create some new PixelArray objects providing a different view
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
59 # of the original array/surface.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
60 newarray = pxarray[2:4,3:5]
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
61 otherarray = pxarray[::2,::2]
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
62
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
63 Subscripts also can be used to do fast rectangular pixel manipulations
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
64 instead of iterating over the x or y axis as above.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
65
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
66 pxarray[::2,:] = (0, 0, 0) # Make each second column black.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
67
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
68 During its lifetime, the PixelArray locks the surface, thus you
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
69 explicitly have to delete it once its not used anymore and the surface
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
70 should perform operations in the same scope.
877
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
71
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
72 New in pygame 1.8. Subscript support is new in pygame 1.8.1.
870
31fa129efd0f Fixed Mask documentation. Added write() method to BufferProxy.
marcus
parents: 866
diff changeset
73 <SECTION>
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
74
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
75 surface
870
31fa129efd0f Fixed Mask documentation. Added write() method to BufferProxy.
marcus
parents: 866
diff changeset
76 Gets the Surface the PixelArray uses.
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
77 PixelArray.surface: Return Surface
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
78
870
31fa129efd0f Fixed Mask documentation. Added write() method to BufferProxy.
marcus
parents: 866
diff changeset
79 The Surface, the PixelArray was created for.
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
80 <END>
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
81
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
82 make_surface
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
83 Creates a new Surface from the current PixelArray.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
84 PixelArray.make_surface (): Return Surface
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
85
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
86 Creates a new Surface from the current PixelArray. Depending on the
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
87 current PixelArray the size, pixel order etc. will be different from the
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
88 original Surface.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
89
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
90 # Create a new surface flipped around the vertical axis.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
91 sf = pxarray[:,::-1].make_surface ()
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
92
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
93 New in pygame.1.8.1.
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
94 <END>
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
95
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
96 replace
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
97 Replaces the passed color in the PixelArray with another one.
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
98 PixelArray.replace (color, replacecolor): Return None
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
99
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
100 Replaces the pixels with the passed color in the PixelArray by changing
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
101 them them to the passed replacement color.
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
102
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
103 New in pygame.1.8.1.
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
104 <END>
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
105 <END>