-
pygame.draw
- pygame module for drawing shapes
— draw a rectangle — draw a polygon — draw a circle — draw an antialiased circle — draw an ellipse — draw an elliptical arc — draw a straight line — draw multiple contiguous straight line segments — draw a straight antialiased line — draw multiple contiguous straight antialiased line segments Draw several simple shapes to a surface. These functions will work for rendering to any format of surface.
Most of the functions take a width argument to represent the size of stroke (thickness) around the edge of the shape. If a width of 0 is passed the shape will be filled (solid).
All the drawing functions respect the clip area for the surface and will be constrained to that area. The functions return a rectangle representing the bounding area of changed pixels. This bounding rectangle is the 'minimum' bounding box that encloses the affected area.
All the drawing functions accept a color argument that is compatible with
pygame.typing.ColorLike
.A color's alpha value will be written directly into the surface (if the surface contains pixel alphas), but the draw function will not draw transparently.
These functions temporarily lock the surface they are operating on. Many sequential drawing calls can be sped up by locking and unlocking the surface object around the draw calls (see
pygame.Surface.lock()
lock the Surface memory for pixel access andpygame.Surface.unlock()
unlock the Surface memory from pixel access).Note
See the
pygame.gfxdraw
pygame module for drawing shapes module for alternative draw methods.- pygame.draw.rect()¶
- draw a rectanglerect(surface, color, rect) -> Rectrect(surface, color, rect, width=0, border_radius=0, border_top_left_radius=-1, border_top_right_radius=-1, border_bottom_left_radius=-1, border_bottom_right_radius=-1) -> Rect
Draws a rectangle on the given surface.
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
rect (Rect) -- rectangle to draw, position and dimensions
width (int) --
(optional) used for line thickness or to indicate that the rectangle is to be filled (not to be confused with the width value of the
rect
parameter)ifwidth == 0
, (default) fill the rectangleifwidth > 0
, used for line thicknessifwidth < 0
, nothing will be drawnChanged in pygame 2.1.1: Drawing rects with width now draws the width correctly inside the rect's area, rather than using an internal call to draw.lines(), which had half the width spill outside the rect area.
border_radius (int) -- (optional) used for drawing rectangle with rounded corners. The supported range is [0, min(height, width) / 2], with 0 representing a rectangle without rounded corners.
border_top_left_radius (int) -- (optional) used for setting the value of top left border. If you don't set this value, it will use the border_radius value.
border_top_right_radius (int) -- (optional) used for setting the value of top right border. If you don't set this value, it will use the border_radius value.
border_bottom_left_radius (int) -- (optional) used for setting the value of bottom left border. If you don't set this value, it will use the border_radius value.
border_bottom_right_radius (int) --
(optional) used for setting the value of bottom right border. If you don't set this value, it will use the border_radius value.
ifborder_radius < 1
it will draw rectangle without rounded cornersif any of border radii has the value< 0
it will use value of the border_radiusIf sum of radii on the same side of the rectangle is greater than the rect size the radiiwill get scaled
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given
rect
parameter and its width and height will be 0- Return type:
Note
The
pygame.Surface.fill()
fill Surface with a solid color method works just as well for drawing filled rectangles and can be hardware accelerated on some platforms.Changed in pygame 2.0.0: Added support for keyword arguments.
Changed in pygame 2.0.0.dev8: Added support for border radius.
- pygame.draw.polygon()¶
- draw a polygonpolygon(surface, color, points) -> Rectpolygon(surface, color, points, width=0) -> Rect
Draws a polygon on the given surface.
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
points (tuple(point) or list(point)) -- a sequence of 3 or more (x, y) coordinates that make up the vertices of the polygon, each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2-Dimensional Vector of 2 ints/floats, e.g.[(x1, y1), (x2, y2), (x3, y3)]
width (int) --
(optional) used for line thickness or to indicate that the polygon is to be filled
if width == 0, (default) fill the polygonif width > 0, used for line thicknessif width < 0, nothing will be drawnNote
When using
width
values> 1
, the edge lines will grow outside the original boundary of the polygon. For more details on how the thickness for edge lines grow, refer to thewidth
notes of thepygame.draw.line()
draw a straight line function.
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the
points
parameter (float values will be truncated) and its width and height will be 0- Return type:
- Raises:
ValueError -- if
len(points) < 3
(must have at least 3 points)TypeError -- if
points
is not a sequence orpoints
does not contain number pairs
Note
For an aapolygon, use
aalines()
withclosed=True
.Changed in pygame 2.0.0: Added support for keyword arguments.
- pygame.draw.circle()¶
- draw a circlecircle(surface, color, center, radius) -> Rectcircle(surface, color, center, radius, width=0, draw_top_right=None, draw_top_left=None, draw_bottom_left=None, draw_bottom_right=None) -> Rect
Draws a circle on the given surface.
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
center (tuple(int or float, int or float) or list(int or float, int or float) or Vector2(int or float, int or float)) -- center point of the circle as a sequence of 2 ints/floats, e.g.
(x, y)
radius (int or float) -- radius of the circle, measured from the
center
parameter, nothing will be drawn if theradius
is less than 1width (int) --
(optional) used for line thickness or to indicate that the circle is to be filled
ifwidth == 0
, (default) fill the circleifwidth > 0
, used for line thicknessifwidth < 0
, nothing will be drawnNote
When using
width
values> 1
, the edge lines will only grow inward.draw_top_right (bool) -- (optional) if this is set to True then the top right corner of the circle will be drawn
draw_top_left (bool) -- (optional) if this is set to True then the top left corner of the circle will be drawn
draw_bottom_left (bool) -- (optional) if this is set to True then the bottom left corner of the circle will be drawn
draw_bottom_right (bool) --
(optional) if this is set to True then the bottom right corner of the circle will be drawn
if any of the draw_circle_part is True then it will draw all circle parts that have the Truevalue, otherwise it will draw the entire circle.
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the
center
parameter value (float values will be truncated) and its width and height will be 0- Return type:
- Raises:
TypeError -- if
center
is not a sequence of two numbersTypeError -- if
radius
is not a number
Changed in pygame 2.0.0: Added support for keyword arguments. Nothing is drawn when the radius is 0 (a pixel at the
center
coordinates used to be drawn when the radius equaled 0). Floats, and Vector2 are accepted for thecenter
param. The drawing algorithm was improved to look more like a circle.Changed in pygame 2.0.0.dev8: Added support for drawing circle quadrants.
- pygame.draw.aacircle()¶
- draw an antialiased circleaacircle(surface, color, center, radius) -> Rectaacircle(surface, color, center, radius, width=0, draw_top_right=None, draw_top_left=None, draw_bottom_left=None, draw_bottom_right=None) -> Rect
Draws an antialiased circle on the given surface. Uses Xiaolin Wu Circle Algorithm. adapted from: https://cgg.mff.cuni.cz/~pepca/ref/WU.pdf
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
center (tuple(int or float, int or float) or list(int or float, int or float) or Vector2(int or float, int or float)) -- center point of the circle as a sequence of 2 ints/floats, e.g.
(x, y)
radius (int or float) -- radius of the circle, measured from the
center
parameter, nothing will be drawn if theradius
is less than 1width (int) --
(optional) used for line thickness or to indicate that the circle is to be filled
ifwidth == 0
, (default) fill the circleifwidth > 0
, used for line thicknessifwidth < 0
, nothing will be drawnNote
When using
width
values> 1
, the edge lines will only grow inward.draw_top_right (bool) -- (optional) if this is set to True then the top right corner of the circle will be drawn
draw_top_left (bool) -- (optional) if this is set to True then the top left corner of the circle will be drawn
draw_bottom_left (bool) -- (optional) if this is set to True then the bottom left corner of the circle will be drawn
draw_bottom_right (bool) --
(optional) if this is set to True then the bottom right corner of the circle will be drawn
if any of the draw_circle_part is True then it will draw all circle parts that have the Truevalue, otherwise it will draw the entire circle.
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the
center
parameter value (float values will be truncated) and its width and height will be 0- Return type:
- Raises:
TypeError -- if
center
is not a sequence of two numbersTypeError -- if
radius
is not a number
New in pygame-ce 2.5.0.
- pygame.draw.ellipse()¶
- draw an ellipseellipse(surface, color, rect) -> Rectellipse(surface, color, rect, width=0) -> Rect
Draws an ellipse on the given surface.
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
rect (Rect) -- rectangle to indicate the position and dimensions of the ellipse, the ellipse will be centered inside the rectangle and bounded by it
width (int) --
(optional) used for line thickness or to indicate that the ellipse is to be filled (not to be confused with the width value of the
rect
parameter)ifwidth == 0
, (default) fill the ellipseifwidth > 0
, used for line thicknessifwidth < 0
, nothing will be drawnNote
When using
width
values> 1
, the edge lines will only grow inward from the original boundary of therect
parameter.
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given
rect
parameter and its width and height will be 0- Return type:
Changed in pygame 2.0.0: Added support for keyword arguments.
- pygame.draw.arc()¶
- draw an elliptical arcarc(surface, color, rect, start_angle, stop_angle) -> Rectarc(surface, color, rect, start_angle, stop_angle, width=1) -> Rect
Draws an elliptical arc on the given surface.
The two angle arguments are given in radians and indicate the start and stop positions of the arc. The arc is drawn in a counterclockwise direction from the
start_angle
to thestop_angle
.- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
rect (Rect) -- rectangle to indicate the position and dimensions of the ellipse which the arc will be based on, the ellipse will be centered inside the rectangle
start_angle (float) -- start angle of the arc in radians
stop_angle (float) --
stop angle of the arc in radians
ifstart_angle < stop_angle
, the arc is drawn in a counterclockwise direction from thestart_angle
to thestop_angle
ifstart_angle > stop_angle
, tau (tau == 2 * pi) will be added to thestop_angle
, if the resulting stop angle value is greater than thestart_angle
the abovestart_angle < stop_angle
case applies, otherwise nothing will be drawnifstart_angle == stop_angle
, nothing will be drawnwidth (int) --
(optional) used for line thickness (not to be confused with the width value of the
rect
parameter)ifwidth == 0
, nothing will be drawnifwidth > 0
, (default is 1) used for line thicknessifwidth < 0
, same aswidth == 0
Note
When using
width
values> 1
, the edge lines will only grow inward from the original boundary of therect
parameter.
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the given
rect
parameter and its width and height will be 0- Return type:
Changed in pygame 2.0.0: Added support for keyword arguments.
- pygame.draw.line()¶
- draw a straight lineline(surface, color, start_pos, end_pos) -> Rectline(surface, color, start_pos, end_pos, width=1) -> Rect
Draws a straight line on the given surface. There are no endcaps. For thick lines the ends are squared off.
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
start_pos (tuple(int or float, int or float) or list(int or float, int or float) or Vector2(int or float, int or float)) -- start position of the line, (x, y)
end_pos (tuple(int or float, int or float) or list(int or float, int or float) or Vector2(int or float, int or float)) -- end position of the line, (x, y)
width (int) --
(optional) used for line thickness
if width >= 1, used for line thickness (default is 1)if width < 1, nothing will be drawnNote
When using
width
values> 1
, lines will grow as follows.For odd
width
values, the thickness of each line grows with the original line being in the center.For even
width
values, the thickness of each line grows with the original line being offset from the center (as there is no exact center line drawn). As a result, lines with a slope < 1 (horizontal-ish) will have 1 more pixel of thickness below the original line (in the y direction). Lines with a slope >= 1 (vertical-ish) will have 1 more pixel of thickness to the right of the original line (in the x direction).
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the
start_pos
parameter value (float values will be truncated) and its width and height will be 0- Return type:
- Raises:
TypeError -- if
start_pos
orend_pos
is not a sequence of two numbers
Changed in pygame 2.0.0: Added support for keyword arguments.
- pygame.draw.lines()¶
- draw multiple contiguous straight line segmentslines(surface, color, closed, points) -> Rectlines(surface, color, closed, points, width=1) -> Rect
Draws a sequence of contiguous straight lines on the given surface. There are no endcaps or miter joints. For thick lines the ends are squared off. Drawing thick lines with sharp corners can have undesired looking results.
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
closed (bool) -- if
True
an additional line segment is drawn between the first and last points in thepoints
sequencepoints (tuple(point) or list(point)) -- a sequence of 2 or more (x, y) coordinates, where each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2-Dimensional Vector of 2 ints/floats and adjacent points will be connected by a line segment, e.g. for the points[(x1, y1), (x2, y2), (x3, y3)]
a line segment will be drawn from(x1, y1)
to(x2, y2)
and from(x2, y2)
to(x3, y3)
, additionally if theclosed
parameter isTrue
another line segment will be drawn from(x3, y3)
to(x1, y1)
width (int) --
(optional) used for line thickness
if width >= 1, used for line thickness (default is 1)if width < 1, nothing will be drawnNote
When using
width
values> 1
refer to thewidth
notes ofline()
for details on how thick lines grow.
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the
points
parameter (float values will be truncated) and its width and height will be 0- Return type:
- Raises:
ValueError -- if
len(points) < 2
(must have at least 2 points)TypeError -- if
points
is not a sequence orpoints
does not contain number pairs
Changed in pygame 2.0.0: Added support for keyword arguments.
- pygame.draw.aaline()¶
- draw a straight antialiased lineaaline(surface, color, start_pos, end_pos) -> Rect aaline(surface, color, start_pos, end_pos, width=1) -> Rect
Draws a straight antialiased line on the given surface. There are no endcaps. For thick lines the ends are squared off.
Note
Regarding float values for coordinates, a point with coordinate consisting of two whole numbers is considered being right in the center of said pixel (and having a height and width of 1 pixel would therefore completely cover it), while a point with coordinate where one (or both) of the numbers have non-zero decimal parts would be partially covering two (or four if both numbers have decimal parts) adjacent pixels, e.g. the point
(1.4, 2)
covers 60% of the pixel(1, 2)
and 40% of the pixel(2,2)
.- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
start_pos (tuple(int or float, int or float) or list(int or float, int or float) or Vector2(int or float, int or float)) -- start position of the line, (x, y)
end_pos (tuple(int or float, int or float) or list(int or float, int or float) or Vector2(int or float, int or float)) -- end position of the line, (x, y)
width (int) --
(optional) used for line thickness
if width >= 1, used for line thickness (default is 1)if width < 1, nothing will be drawn
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the
start_pos
parameter value (float values will be truncated) and its width and height will be 0- Return type:
- Raises:
TypeError -- if
start_pos
orend_pos
is not a sequence of two numbers
Changed in pygame 2.0.0: Added support for keyword arguments.
Changed in pygame-ce 2.4.0: Removed deprecated 'blend' argument
Changed in pygame-ce 2.5.0:
blend
argument readded for backcompat, but will always raise a deprecation exception when usedChanged in pygame-ce 2.5.2: Added line width
- pygame.draw.aalines()¶
- draw multiple contiguous straight antialiased line segmentsaalines(surface, color, closed, points) -> Rect
Draws a sequence of contiguous straight antialiased lines on the given surface.
- Parameters:
surface (Surface) -- surface to draw on
color (
pygame.typing.ColorLike
) -- color to draw with, the alpha value is optional if using a tuple(RGB[A])
closed (bool) -- if
True
an additional line segment is drawn between the first and last points in thepoints
sequencepoints (tuple(point) or list(point)) -- a sequence of 2 or more (x, y) coordinates, where each point in the sequence must be a tuple/list/
pygame.math.Vector2
a 2-Dimensional Vector of 2 ints/floats and adjacent points will be connected by a line segment, e.g. for the points[(x1, y1), (x2, y2), (x3, y3)]
a line segment will be drawn from(x1, y1)
to(x2, y2)
and from(x2, y2)
to(x3, y3)
, additionally if theclosed
parameter isTrue
another line segment will be drawn from(x3, y3)
to(x1, y1)
- Returns:
a rect bounding the changed pixels, if nothing is drawn the bounding rect's position will be the position of the first point in the
points
parameter (float values will be truncated) and its width and height will be 0- Return type:
- Raises:
ValueError -- if
len(points) < 2
(must have at least 2 points)TypeError -- if
points
is not a sequence orpoints
does not contain number pairs
Changed in pygame 2.0.0: Added support for keyword arguments.
Changed in pygame-ce 2.4.0: Removed deprecated
blend
argumentChanged in pygame-ce 2.5.0:
blend
argument readded for backcompat, but will always raise a deprecation exception when used
import pygame from math import pi # Initialize pygame pygame.init() # Set the height and width of the screen size = [400, 300] screen = pygame.display.set_mode(size) pygame.display.set_caption("Example code for the draw module") # Loop until the user clicks the close button. done = False clock = pygame.time.Clock() while not done: # This limits the while loop to a max of 60 times per second. # Leave this out and we will use all CPU we can. clock.tick(60) for event in pygame.event.get(): # User did something if event.type == pygame.QUIT: # If user clicked close done = True # Flag that we are done so we exit this loop # Clear the screen and set the screen background screen.fill("white") # Draw on the screen a green line from (0, 0) to (50, 30) # 5 pixels wide. Uses (r, g, b) color - medium sea green. pygame.draw.line(screen, (60, 179, 113), [0, 0], [50, 30], 5) # Draw on the screen a green antialiased line from (0, 25) to (50, 55) # 5 pixels wide. Uses (r, g, b) color - medium sea green. pygame.draw.aaline(screen, (60, 179, 113), [0, 25], [50, 55], 5) # Draw on the screen a green line from (0, 50) to (50, 80) # Because it is an antialiased line, it is 1 pixel wide. # Uses (r, g, b) color - medium sea green. pygame.draw.aaline(screen, (60, 179, 113), [0, 50], [50, 80], True) # Draw on the screen 3 black lines, each 5 pixels wide. # The 'False' means the first and last points are not connected. pygame.draw.lines( screen, "black", False, [[0, 80], [50, 90], [200, 80], [220, 30]], 5 ) # Draw a rectangle outline pygame.draw.rect(screen, "black", [75, 10, 50, 20], 2) # Draw a solid rectangle. Same color as "black" above, specified in a new way pygame.draw.rect(screen, (0, 0, 0), [150, 10, 50, 20]) # Draw a rectangle with rounded corners pygame.draw.rect(screen, "green", [115, 210, 70, 40], 10, border_radius=15) pygame.draw.rect( screen, "red", [135, 260, 50, 30], 0, border_radius=10, border_top_left_radius=0, border_bottom_right_radius=15, ) # Draw an ellipse outline, using a rectangle as the outside boundaries pygame.draw.ellipse(screen, "red", [225, 10, 50, 20], 2) # Draw an solid ellipse, using a rectangle as the outside boundaries pygame.draw.ellipse(screen, "red", [300, 10, 50, 20]) # This draws a triangle using the polygon command pygame.draw.polygon(screen, "black", [[100, 100], [0, 200], [200, 200]], 5) # Draw an arc as part of an ellipse. # Use radians to determine what angle to draw. pygame.draw.arc(screen, "black", [210, 75, 150, 125], 0, pi / 2, 2) pygame.draw.arc(screen, "green", [210, 75, 150, 125], pi / 2, pi, 2) pygame.draw.arc(screen, "blue", [210, 75, 150, 125], pi, 3 * pi / 2, 2) pygame.draw.arc(screen, "red", [210, 75, 150, 125], 3 * pi / 2, 2 * pi, 2) # Draw a circle pygame.draw.circle(screen, "blue", [60, 250], 40) # Draw an antialiased circle with 3 pixels wide line pygame.draw.aacircle(screen, "green", [340, 250], 40, 3) # Draw an antialiased top right circle quadrant with 4 pixels wide line pygame.draw.aacircle(screen, "red", [340, 250], 20, 4, draw_top_right=True) # Draw an antialiased bottom left filled circle quadrant pygame.draw.aacircle(screen, "blue", [340, 250], 20, draw_bottom_left=True) # Draw only one circle quadrant pygame.draw.circle(screen, "blue", [250, 250], 40, 0, draw_top_right=True) pygame.draw.circle(screen, "red", [250, 250], 40, 30, draw_top_left=True) pygame.draw.circle(screen, "green", [250, 250], 40, 20, draw_bottom_left=True) pygame.draw.circle(screen, "black", [250, 250], 40, 10, draw_bottom_right=True) # Go ahead and update the screen with what we've drawn. # This MUST happen after all the other drawing commands. pygame.display.flip() # Be IDLE friendly pygame.quit()
Edit on GitHub