1
.. include:: common.txt
6
.. module:: pygame.gfxdraw
7
:synopsis: pygame module for drawing shapes
9
| :sl:`pygame module for drawing shapes`
11
EXPERIMENTAL!: meaning this api may change, or dissapear in later pygame
12
releases. If you use this, your code will break with the next pygame release.
14
Draw several shapes to a surface.
16
Most of the functions accept a color argument that is an ``RGB`` triplet. These
17
can also accept an ``RGBA`` quadruplet. The color argument can also be an
18
integer pixel value that is already mapped to the Surface's pixel format.
20
For all functions the arguments are strictly positional. Only integers are
21
accepted for coordinates and radii.
23
For functions like rectangle that accept a rect argument any (x, y, w, h)
24
sequence is accepted, though :mod:`pygame.Rect` instances are prefered. Note
25
that for a :mod:`pygame.Rect` the drawing will not include
26
``Rect.bottomright``. The right and bottom attributes of a Rect lie one pixel
27
outside of the Rect's boarder.
29
To draw an anti aliased and filled shape, first use the aa* version of
30
the function, and then use the filled version. For example ::
33
surf.fill((255, 255, 255))
34
pygame.gfxdraw.aacircle(surf, x, y, 30, col)
35
pygame.gfxdraw.filled_circle(surf, x, y, 30, col)
37
Note that pygame does not automatically import pygame.gfxdraw, so you need to
38
import pygame.gfxdraw before using it.
40
Threading note: each of the functions releases the GIL during the C part of the call.
42
The pygame.gfxdraw module differs from the draw module in the API it uses, and
43
also the different functions available to draw. It also wraps the primitives
44
from the library called SDL_gfx, rather than using modified versions.
52
| :sg:`pixel(surface, x, y, color) -> None`
54
Draws a single pixel onto a surface.
56
.. ## pygame.gfxdraw.pixel ##
60
| :sl:`draw a horizontal line`
61
| :sg:`hline(surface, x1, x2, y, color) -> None`
63
Draws a straight horizontal line on a Surface from x1 to x2 for
64
the given y coordinate.
66
.. ## pygame.gfxdraw.hline ##
70
| :sl:`draw a vertical line`
71
| :sg:`vline(surface, x, y1, y2, color) -> None`
73
Draws a straight vertical line on a Surface from y1 to y2 on
74
the given x coordinate.
76
.. ## pygame.gfxdraw.vline ##
78
.. function:: rectangle
80
| :sl:`draw a rectangle`
81
| :sg:`rectangle(surface, rect, color) -> None`
83
Draws the rectangle edges onto the surface. The given Rect is the area of the
86
Keep in mind the ``Surface.fill()`` method works just as well for drawing
87
filled rectangles. In fact the ``Surface.fill()`` can be hardware
88
accelerated on some platforms with both software and hardware display modes.
90
.. ## pygame.gfxdraw.rectangle ##
95
| :sg:`box(surface, rect, color) -> None`
97
Draws a box (a rect) onto a surface.
99
.. ## pygame.gfxdraw.box ##
104
| :sg:`line(surface, x1, y1, x2, y2, color) -> None`
106
Draws a straight line on a Surface. There are no endcaps.
108
.. ## pygame.gfxdraw.line ##
112
| :sl:`draw a circle`
113
| :sg:`circle(surface, x, y, r, color) -> None`
115
Draws the edges of a circular shape on the Surface. The pos argument is
116
the center of the circle, and radius is the size. The circle is not
119
.. ## pygame.gfxdraw.circle ##
124
| :sg:`arc(surface, x, y, r, start, end, color) -> None`
126
Draws an arc onto a surface.
128
.. ## pygame.gfxdraw.arc ##
130
.. function:: aacircle
132
| :sl:`draw an anti-aliased circle`
133
| :sg:`aacircle(surface, x, y, r, color) -> None`
135
Draws the edges of an anti aliased circle onto a surface.
137
.. ## pygame.gfxdraw.aacircle ##
139
.. function:: filled_circle
141
| :sl:`draw a filled circle`
142
| :sg:`filled_circle(surface, x, y, r, color) -> None`
144
Draws a filled circle onto a surface. So the inside of the circle will
145
be filled with the given color.
147
.. ## pygame.gfxdraw.filled_circle ##
149
.. function:: ellipse
151
| :sl:`draw an ellipse`
152
| :sg:`ellipse(surface, x, y, rx, ry, color) -> None`
154
Draws the edges of an ellipse onto a surface.
156
.. ## pygame.gfxdraw.ellipse ##
158
.. function:: aaellipse
160
| :sl:`draw an anti-aliased ellipse`
161
| :sg:`aaellipse(surface, x, y, rx, ry, color) -> None`
163
Draws anti aliased edges of an ellipse onto a surface.
165
.. ## pygame.gfxdraw.aaellipse ##
167
.. function:: filled_ellipse
169
| :sl:`draw a filled ellipse`
170
| :sg:`filled_ellipse(surface, x, y, rx, ry, color) -> None`
172
Draws a filled ellipse onto a surface. So the inside of the elipse will
173
be filled with the given color.
175
.. ## pygame.gfxdraw.filled_ellipse ##
180
| :sg:`pie(surface, x, y, r, start, end, color) -> None`
182
Draws a pie onto the surface.
184
.. ## pygame.gfxdraw.pie ##
188
| :sl:`draw a triangle`
189
| :sg:`trigon(surface, x1, y1, x2, y2, x3, y3, color) -> None`
191
Draws the edges of a trigon onto a surface. A trigon is a triangle.
193
.. ## pygame.gfxdraw.trigon ##
195
.. function:: aatrigon
197
| :sl:`draw an anti-aliased triangle`
198
| :sg:`aatrigon(surface, x1, y1, x2, y2, x3, y3, color) -> None`
200
Draws the anti aliased edges of a trigon onto a surface. A trigon is a triangle.
202
.. ## pygame.gfxdraw.aatrigon ##
204
.. function:: filled_trigon
206
| :sl:`draw a filled trigon`
207
| :sg:`filled_trigon(surface, x1, y1, x2, y2, x3, y3, color) -> None`
209
Draws a filled trigon onto a surface. So the inside of the trigon will
210
be filled with the given color.
212
.. ## pygame.gfxdraw.filled_trigon ##
214
.. function:: polygon
216
| :sl:`draw a polygon`
217
| :sg:`polygon(surface, points, color) -> None`
219
Draws the edges of a polygon onto a surface.
221
.. ## pygame.gfxdraw.polygon ##
223
.. function:: aapolygon
225
| :sl:`draw an anti-aliased polygon`
226
| :sg:`aapolygon(surface, points, color) -> None`
228
Draws the anti aliased edges of a polygon onto a surface.
230
.. ## pygame.gfxdraw.aapolygon ##
232
.. function:: filled_polygon
234
| :sl:`draw a filled polygon`
235
| :sg:`filled_polygon(surface, points, color) -> None`
237
Draws a filled polygon onto a surface. So the inside of the polygon will
238
be filled with the given color.
240
.. ## pygame.gfxdraw.filled_polygon ##
242
.. function:: textured_polygon
244
| :sl:`draw a textured polygon`
245
| :sg:`textured_polygon(surface, points, texture, tx, ty) -> None`
247
Draws a textured polygon onto a surface.
249
A per-pixel alpha texture blit to a per-pixel alpha surface will differ from
250
a ``Surface.blit()`` blit. Also, a per-pixel alpha texture cannot be used
251
with an 8-bit per pixel destination.
253
.. ## pygame.gfxdraw.textured_polygon ##
257
| :sl:`draw a bezier curve`
258
| :sg:`bezier(surface, points, steps, color) -> None`
260
Draws a bezier onto a surface.
262
.. ## pygame.gfxdraw.bezier ##
264
.. ## pygame.gfxdraw ##