
pygame.gfxdraw
 pygame module for drawing shapes
— draw a pixel — draw a horizontal line — draw a vertical line — draw a line — draw a rectangle — draw a filled rectangle — draw a circle — draw an antialiased circle — draw a filled circle — draw an ellipse — draw an antialiased ellipse — draw a filled ellipse — draw an arc — draw a pie — draw a trigon/triangle — draw an antialiased trigon/triangle — draw a filled trigon/triangle — draw a polygon — draw an antialiased polygon — draw a filled polygon — draw a textured polygon — draw a Bezier curve EXPERIMENTAL!: This API may change or disappear in later pygame releases. If you use this, your code may break with the next pygame release.
The pygame package does not import gfxdraw automatically when loaded, so it must imported explicitly to be used.
import pygame import pygame.gfxdraw
For all functions the arguments are strictly positional and integers are accepted for coordinates and radii. The
color
argument can be one of the following formats:a
pygame.Color
pygame object for color representations objectan
(RGB)
triplet (tuple/list)an
(RGBA)
quadruplet (tuple/list)
The functions
rectangle()
andbox()
will accept any(x, y, w, h)
sequence for theirrect
argument, thoughpygame.Rect
pygame object for storing rectangular coordinates instances are preferred.To draw a filled antialiased shape, first use the antialiased (aa*) version of the function, and then use the filled (filled_*) version. For example:
col = (255, 0, 0) surf.fill((255, 255, 255)) pygame.gfxdraw.aacircle(surf, x, y, 30, col) pygame.gfxdraw.filled_circle(surf, x, y, 30, col)
Note
For threading, each of the functions releases the GIL during the C part of the call.
Note
See the
pygame.draw
pygame module for drawing shapes module for alternative draw methods. Thepygame.gfxdraw
module differs from thepygame.draw
pygame module for drawing shapes module in the API it uses and the different draw functions available.pygame.gfxdraw
wraps the primitives from the library called SDL_gfx, rather than using modified versions.New in pygame 1.9.0.
 pygame.gfxdraw.pixel()¶
 draw a pixelpixel(surface, x, y, color, /) > None
Draws a single pixel, at position (x ,y), on the given surface.
 pygame.gfxdraw.hline()¶
 draw a horizontal linehline(surface, x1, x2, y, color, /) > None
Draws a straight horizontal line (
(x1, y)
to(x2, y)
) on the given surface. There are no endcaps. Parameters:
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.vline()¶
 draw a vertical linevline(surface, x, y1, y2, color, /) > None
Draws a straight vertical line (
(x, y1)
to(x, y2)
) on the given surface. There are no endcaps. Parameters:
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.line()¶
 draw a lineline(surface, x1, y1, x2, y2, color, /) > None
Draws a straight line (
(x1, y1)
to(x2, y2)
) on the given surface. There are no endcaps. Parameters:
surface (Surface)  surface to draw on
x1 (int)  x coordinate of one end of the line
y1 (int)  y coordinate of one end of the line
x2 (int)  x coordinate of the other end of the line
y2 (int)  y coordinate of the other end of the line
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.rectangle()¶
 draw a rectanglerectangle(surface, rect, color, /) > None
Draws an unfilled rectangle on the given surface. For a filled rectangle use
box()
. Parameters:
 Returns:
None
 Return type:
NoneType
Note
The
rect.bottom
andrect.right
attributes of apygame.Rect
pygame object for storing rectangular coordinates always lie one pixel outside of its actual border. Therefore, these values will not be included as part of the drawing.
 pygame.gfxdraw.box()¶
 draw a filled rectanglebox(surface, rect, color, /) > None
Draws a filled rectangle on the given surface. For an unfilled rectangle use
rectangle()
. Parameters:
 Returns:
None
 Return type:
NoneType
Note
The
rect.bottom
andrect.right
attributes of apygame.Rect
pygame object for storing rectangular coordinates always lie one pixel outside of its actual border. Therefore, these values will not be included as part of the drawing.Note
The
pygame.Surface.fill()
fill Surface with a solid color method works just as well for drawing filled rectangles. In factpygame.Surface.fill()
fill Surface with a solid color can be hardware accelerated on some platforms with both software and hardware display modes.
 pygame.gfxdraw.circle()¶
 draw a circlecircle(surface, x, y, r, color, /) > None
Draws an unfilled circle on the given surface. For a filled circle use
filled_circle()
. Parameters:
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.aacircle()¶
 draw an antialiased circleaacircle(surface, x, y, r, color, /) > None
Draws an unfilled antialiased circle on the given surface.
 Parameters:
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.filled_circle()¶
 draw a filled circlefilled_circle(surface, x, y, r, color, /) > None
Draws a filled circle on the given surface. For an unfilled circle use
circle()
. Parameters:
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.ellipse()¶
 draw an ellipseellipse(surface, x, y, rx, ry, color, /) > None
Draws an unfilled ellipse on the given surface. For a filled ellipse use
filled_ellipse()
. Parameters:
surface (Surface)  surface to draw on
x (int)  x coordinate of the center of the ellipse
y (int)  y coordinate of the center of the ellipse
rx (int)  horizontal radius of the ellipse
ry (int)  vertical radius of the ellipse
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.aaellipse()¶
 draw an antialiased ellipseaaellipse(surface, x, y, rx, ry, color, /) > None
Draws an unfilled antialiased ellipse on the given surface.
 Parameters:
surface (Surface)  surface to draw on
x (int)  x coordinate of the center of the ellipse
y (int)  y coordinate of the center of the ellipse
rx (int)  horizontal radius of the ellipse
ry (int)  vertical radius of the ellipse
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.filled_ellipse()¶
 draw a filled ellipsefilled_ellipse(surface, x, y, rx, ry, color, /) > None
Draws a filled ellipse on the given surface. For an unfilled ellipse use
ellipse()
. Parameters:
surface (Surface)  surface to draw on
x (int)  x coordinate of the center of the ellipse
y (int)  y coordinate of the center of the ellipse
rx (int)  horizontal radius of the ellipse
ry (int)  vertical radius of the ellipse
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.arc()¶
 draw an arcarc(surface, x, y, r, start_angle, stop_angle, color, /) > None
Draws an arc on the given surface. For an arc with its endpoints connected to its center use
pie()
.The two angle arguments are given in degrees and indicate the start and stop positions of the arc. The arc is drawn in a clockwise direction from the
start_angle
to thestop_angle
. Ifstart_angle == stop_angle
, nothing will be drawn Parameters:
surface (Surface)  surface to draw on
x (int)  x coordinate of the center of the arc
y (int)  y coordinate of the center of the arc
r (int)  radius of the arc
start_angle (int)  start angle in degrees
stop_angle (int)  stop angle in degrees
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
Note
This function uses degrees while the
pygame.draw.arc()
draw an elliptical arc function uses radians.
 pygame.gfxdraw.pie()¶
 draw a piepie(surface, x, y, r, start_angle, stop_angle, color, /) > None
Draws an unfilled pie on the given surface. A pie is an
arc()
with its endpoints connected to its center.The two angle arguments are given in degrees and indicate the start and stop positions of the pie. The pie is drawn in a clockwise direction from the
start_angle
to thestop_angle
. Ifstart_angle == stop_angle
, a straight line will be drawn from the center position at the given angle, to a length of the radius. Parameters:
surface (Surface)  surface to draw on
x (int)  x coordinate of the center of the pie
y (int)  y coordinate of the center of the pie
r (int)  radius of the pie
start_angle (int)  start angle in degrees
stop_angle (int)  stop angle in degrees
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.trigon()¶
 draw a trigon/triangletrigon(surface, x1, y1, x2, y2, x3, y3, color, /) > None
Draws an unfilled trigon (triangle) on the given surface. For a filled trigon use
filled_trigon()
.A trigon can also be drawn using
polygon()
e.g.polygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
 Parameters:
surface (Surface)  surface to draw on
x1 (int)  x coordinate of the first corner of the trigon
y1 (int)  y coordinate of the first corner of the trigon
x2 (int)  x coordinate of the second corner of the trigon
y2 (int)  y coordinate of the second corner of the trigon
x3 (int)  x coordinate of the third corner of the trigon
y3 (int)  y coordinate of the third corner of the trigon
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.aatrigon()¶
 draw an antialiased trigon/triangleaatrigon(surface, x1, y1, x2, y2, x3, y3, color, /) > None
Draws an unfilled antialiased trigon (triangle) on the given surface.
An aatrigon can also be drawn using
aapolygon()
e.g.aapolygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
 Parameters:
surface (Surface)  surface to draw on
x1 (int)  x coordinate of the first corner of the trigon
y1 (int)  y coordinate of the first corner of the trigon
x2 (int)  x coordinate of the second corner of the trigon
y2 (int)  y coordinate of the second corner of the trigon
x3 (int)  x coordinate of the third corner of the trigon
y3 (int)  y coordinate of the third corner of the trigon
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.filled_trigon()¶
 draw a filled trigon/trianglefilled_trigon(surface, x1, y1, x2, y2, x3, y3, color, /) > None
Draws a filled trigon (triangle) on the given surface. For an unfilled trigon use
trigon()
.A filled_trigon can also be drawn using
filled_polygon()
e.g.filled_polygon(surface, ((x1, y1), (x2, y2), (x3, y3)), color)
 Parameters:
surface (Surface)  surface to draw on
x1 (int)  x coordinate of the first corner of the trigon
y1 (int)  y coordinate of the first corner of the trigon
x2 (int)  x coordinate of the second corner of the trigon
y2 (int)  y coordinate of the second corner of the trigon
x3 (int)  x coordinate of the third corner of the trigon
y3 (int)  y coordinate of the third corner of the trigon
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 pygame.gfxdraw.polygon()¶
 draw a polygonpolygon(surface, points, color, /) > None
Draws an unfilled polygon on the given surface. For a filled polygon use
filled_polygon()
.The adjacent points in the
points
argument, as well as the first and last points, will be connected by line segments. e.g. For the points[(x1, y1), (x2, y2), (x3, y3)]
a line segment will be drawn from(x1, y1)
to(x2, y2)
, from(x2, y2)
to(x3, y3)
, and from(x3, y3)
to(x1, y1)
. Parameters:
surface (Surface)  surface to draw on
points (tuple(point) or list(point))  a sequence of 3 or more (x, y) coordinates, where each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2Dimensional Vector of 2 ints/floats (float values will be truncated)color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 Raises:
ValueError  if
len(points) < 3
(must have at least 3 points)IndexError  if
len(point) < 2
(each point must have at least 2 items)
 pygame.gfxdraw.aapolygon()¶
 draw an antialiased polygonaapolygon(surface, points, color, /) > None
Draws an unfilled antialiased polygon on the given surface.
The adjacent points in the
points
argument, as well as the first and last points, will be connected by line segments. e.g. For the points[(x1, y1), (x2, y2), (x3, y3)]
a line segment will be drawn from(x1, y1)
to(x2, y2)
, from(x2, y2)
to(x3, y3)
, and from(x3, y3)
to(x1, y1)
. Parameters:
surface (Surface)  surface to draw on
points (tuple(point) or list(point))  a sequence of 3 or more (x, y) coordinates, where each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2Dimensional Vector of 2 ints/floats (float values will be truncated)color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 Raises:
ValueError  if
len(points) < 3
(must have at least 3 points)IndexError  if
len(point) < 2
(each point must have at least 2 items)
 pygame.gfxdraw.filled_polygon()¶
 draw a filled polygonfilled_polygon(surface, points, color, /) > None
Draws a filled polygon on the given surface. For an unfilled polygon use
polygon()
.The adjacent points in the
points
argument, as well as the first and last points, will be connected by line segments. e.g. For the points[(x1, y1), (x2, y2), (x3, y3)]
a line segment will be drawn from(x1, y1)
to(x2, y2)
, from(x2, y2)
to(x3, y3)
, and from(x3, y3)
to(x1, y1)
. Parameters:
surface (Surface)  surface to draw on
points (tuple(point) or list(point))  a sequence of 3 or more (x, y) coordinates, where each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2Dimensional Vector of 2 ints/floats (float values will be truncated)`color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 Raises:
ValueError  if
len(points) < 3
(must have at least 3 points)IndexError  if
len(point) < 2
(each point must have at least 2 items)
 pygame.gfxdraw.textured_polygon()¶
 draw a textured polygontextured_polygon(surface, points, texture, tx, ty, /) > None
Draws a textured polygon on the given surface. For better performance, the surface and the texture should have the same format.
A perpixel alpha texture blit to a perpixel alpha surface will differ from a
pygame.Surface.blit()
draw another surface onto this one blit. Also, a perpixel alpha texture cannot be used with an 8bit per pixel destination.The adjacent points in the
points
argument, as well as the first and last points, will be connected by line segments. e.g. For the points[(x1, y1), (x2, y2), (x3, y3)]
a line segment will be drawn from(x1, y1)
to(x2, y2)
, from(x2, y2)
to(x3, y3)
, and from(x3, y3)
to(x1, y1)
. Parameters:
surface (Surface)  surface to draw on
points (tuple(point) or list(point))  a sequence of 3 or more (x, y) coordinates, where each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2Dimensional Vector of 2 ints/floats (float values will be truncated)texture (Surface)  texture to draw on the polygon
tx (int)  x offset of the texture
ty (int)  y offset of the texture
 Returns:
None
 Return type:
NoneType
 Raises:
ValueError  if
len(points) < 3
(must have at least 3 points)IndexError  if
len(point) < 2
(each point must have at least 2 items)
 pygame.gfxdraw.bezier()¶
 draw a Bezier curvebezier(surface, points, steps, color, /) > None
Draws a Bézier curve on the given surface.
 Parameters:
surface (Surface)  surface to draw on
points (tuple(point) or list(point))  a sequence of 3 or more (x, y) coordinates used to form a curve, where each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2Dimensional Vector of 2 ints/floats (float values will be truncated)steps (int)  number of steps for the interpolation, the minimum is 2
color (Color or tuple(int, int, int, [int]))  color to draw with, the alpha value is optional if using a tuple
(RGB[A])
 Returns:
None
 Return type:
NoneType
 Raises:
ValueError  if
steps < 2
ValueError  if
len(points) < 3
(must have at least 3 points)IndexError  if
len(point) < 2
(each point must have at least 2 items)
Note
This function supports up to around 150200 points before the algorithm breaks down.
Edit on GitHub