pygame module for drawing shapes

pygame.draw.rect — draw a rectangle pygame.draw.polygon — draw a polygon pygame.draw.circle — draw a circle pygame.draw.ellipse — draw an ellipse pygame.draw.arc — draw an elliptical arc pygame.draw.line — draw a straight line pygame.draw.lines — draw multiple contiguous straight line segments pygame.draw.aaline — draw a straight antialiased line pygame.draw.aalines — 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. Rendering to hardware surfaces will be slower than regular software surfaces.

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 can be one of the following formats:

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 and pygame.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 rectangle rect(surface, color, rect) -> Rect rect(surface, color, rect, width=0, border_radius=0, border_radius=-1, border_top_left_radius=-1, border_top_right_radius=-1, border_bottom_left_radius=-1) -> Rect Draws a rectangle on the given surface. Parameters: surface (Surface) -- surface to draw on

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple rect (Rect) -- rectangle to draw, position and dimensions

(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) if width == 0 , (default) fill the rectangle if width > 0 , used for line thickness if width < 0 , nothing will be drawn

Note When using width values > 1 , the edge lines will grow outside the original boundary of the rect. For more details on how the thickness for edge lines grow, refer to the width notes of the pygame.draw.line() draw a straight line function.

(int) -- 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.

(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.

(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.

(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.

(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. if border_radius < 1 it will draw rectangle without rounded corners if any of border radii has the value < 0 it will use value of the border_radius If sum of radii on the same side of the rectangle is greater than the rect size the radii will 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: Rect 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 with both software and hardware display modes. 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 polygon polygon(surface, color, points) -> Rect polygon(surface, color, points, width=0) -> Rect Draws a polygon on the given surface. Parameters: surface (Surface) -- surface to draw on

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple points (tuple(coordinate) or list(coordinate)) -- a sequence of 3 or more (x, y) coordinates that make up the vertices of the polygon, each coordinate 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)]

(tuple(coordinate) or list(coordinate)) -- a sequence of 3 or more (x, y) coordinates that make up the vertices of the polygon, each coordinate in the sequence must be a tuple/list/ of 2 ints/floats, e.g. width (int) -- (optional) used for line thickness or to indicate that the polygon is to be filled if width == 0, (default) fill the polygon if width > 0, used for line thickness if width < 0, nothing will be drawn

Note 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 the width notes of the pygame.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: Rect Raises: ValueError -- if len(points) < 3 (must have at least 3 points)

-- if (must have at least 3 points) TypeError -- if points is not a sequence or points does not contain number pairs Note For an aapolygon, use aalines() with closed=True . Changed in pygame 2.0.0: Added support for keyword arguments.

pygame.draw. circle ( ) ¶ draw a circle circle(surface, color, center, radius) -> Rect circle(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

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple 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)

(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. radius (int or float) -- radius of the circle, measured from the center parameter, nothing will be drawn if the radius is less than 1

(int or float) -- radius of the circle, measured from the parameter, nothing will be drawn if the is less than 1 width (int) -- (optional) used for line thickness or to indicate that the circle is to be filled if width == 0 , (default) fill the circle if width > 0 , used for line thickness if width < 0 , nothing will be drawn

Note When using width values > 1 , the edge lines will only grow inward.

(int) -- draw_top_right (bool) -- (optional) if this is set to True than the top right corner of the circle will be drawn

(bool) -- (optional) if this is set to True than the top right corner of the circle will be drawn draw_top_left (bool) -- (optional) if this is set to True than the top left corner of the circle will be drawn

(bool) -- (optional) if this is set to True than the top left corner of the circle will be drawn draw_bottom_left (bool) -- (optional) if this is set to True than the bottom left corner of the circle will be drawn

(bool) -- (optional) if this is set to True than the bottom left corner of the circle will be drawn draw_bottom_right (bool) -- (optional) if this is set to True than the bottom right corner of the circle will be drawn if any of the draw_circle_part is True than it will draw all circle parts that have the True value, 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: Rect Raises: TypeError -- if center is not a sequence of two numbers

-- if is not a sequence of two numbers TypeError -- 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 the center 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. ellipse ( ) ¶ draw an ellipse ellipse(surface, color, rect) -> Rect ellipse(surface, color, rect, width=0) -> Rect Draws an ellipse on the given surface. Parameters: surface (Surface) -- surface to draw on

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple rect (Rect) -- rectangle to indicate the position and dimensions of the ellipse, the ellipse will be centered inside the rectangle and bounded by it

(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) if width == 0 , (default) fill the ellipse if width > 0 , used for line thickness if width < 0 , nothing will be drawn

Note When using width values > 1 , the edge lines will only grow inward from the original boundary of the rect 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: Rect Changed in pygame 2.0.0: Added support for keyword arguments.

pygame.draw. arc ( ) ¶ draw an elliptical arc arc(surface, color, rect, start_angle, stop_angle) -> Rect arc(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 the stop_angle . Parameters: surface (Surface) -- surface to draw on

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple 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

(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

(float) -- start angle of the arc in radians stop_angle (float) -- stop angle of the arc in radians if start_angle < stop_angle , the arc is drawn in a counterclockwise direction from the start_angle to the stop_angle if start_angle > stop_angle , tau (tau == 2 * pi) will be added to the stop_angle , if the resulting stop angle value is greater than the start_angle the above start_angle < stop_angle case applies, otherwise nothing will be drawn if start_angle == stop_angle , nothing will be drawn



(float) -- width (int) -- (optional) used for line thickness (not to be confused with the width value of the rect parameter) if width == 0 , nothing will be drawn if width > 0 , (default is 1) used for line thickness if width < 0 , same as width == 0 Note When using width values > 1 , the edge lines will only grow inward from the original boundary of the rect 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: Rect Changed in pygame 2.0.0: Added support for keyword arguments.

pygame.draw. line ( ) ¶ draw a straight line line(surface, color, start_pos, end_pos, width) -> Rect line(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

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple 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)

(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)

(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

Note 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: Rect Raises: TypeError -- if start_pos or end_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 segments lines(surface, color, closed, points) -> Rect lines(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

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple closed (bool) -- if True an additional line segment is drawn between the first and last points in the points sequence

(bool) -- if an additional line segment is drawn between the first and last points in the sequence points (tuple(coordinate) or list(coordinate)) -- a sequence of 2 or more (x, y) coordinates, where each coordinate in the sequence must be a tuple/list/ pygame.math.Vector2 a 2-Dimensional Vector of 2 ints/floats and adjacent coordinates 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 the closed parameter is True another line segment will be drawn from (x3, y3) to (x1, y1)

(tuple(coordinate) or list(coordinate)) -- a sequence of 2 or more (x, y) coordinates, where each coordinate in the sequence must be a tuple/list/ of 2 ints/floats and adjacent coordinates will be connected by a line segment, e.g. for the points a line segment will be drawn from to and from to , additionally if the parameter is another line segment will be drawn from to width (int) -- (optional) used for line thickness if width >= 1, used for line thickness (default is 1) if width < 1, nothing will be drawn

Note When using width values > 1 refer to the width notes of line() 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: Rect Raises: ValueError -- if len(points) < 2 (must have at least 2 points)

-- if (must have at least 2 points) TypeError -- if points is not a sequence or points does not contain number pairs Changed in pygame 2.0.0: Added support for keyword arguments.

pygame.draw. aaline ( ) ¶ draw a straight antialiased line aaline(surface, color, start_pos, end_pos) -> Rect aaline(surface, color, start_pos, end_pos, blend=1) -> Rect Draws a straight antialiased line on the given surface. Parameters: surface (Surface) -- surface to draw on

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple 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)

(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)

(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) blend (int) -- (optional) if non-zero (default) the line will be blended with the surface's existing pixel shades, otherwise it will overwrite them 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: Rect Raises: TypeError -- if start_pos or end_pos is not a sequence of two numbers Changed in pygame 2.0.0: Added support for keyword arguments.

pygame.draw. aalines ( ) ¶ draw multiple contiguous straight antialiased line segments aalines(surface, color, closed, points) -> Rect aalines(surface, color, closed, points, blend=1) -> Rect Draws a sequence of contiguous straight antialiased lines on the given surface. Parameters: surface (Surface) -- surface to draw on

(Surface) -- surface to draw on color (Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple (RGB[A])

(Color or int or tuple(int, int, int, [int])) -- color to draw with, the alpha value is optional if using a tuple closed (bool) -- if True an additional line segment is drawn between the first and last points in the points sequence

(bool) -- if an additional line segment is drawn between the first and last points in the sequence points (tuple(coordinate) or list(coordinate)) -- a sequence of 2 or more (x, y) coordinates, where each coordinate in the sequence must be a tuple/list/ pygame.math.Vector2 a 2-Dimensional Vector of 2 ints/floats and adjacent coordinates 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 the closed parameter is True another line segment will be drawn from (x3, y3) to (x1, y1)

(tuple(coordinate) or list(coordinate)) -- a sequence of 2 or more (x, y) coordinates, where each coordinate in the sequence must be a tuple/list/ of 2 ints/floats and adjacent coordinates will be connected by a line segment, e.g. for the points a line segment will be drawn from to and from to , additionally if the parameter is another line segment will be drawn from to blend (int) -- (optional) if non-zero (default) each line will be blended with the surface's existing pixel shades, otherwise the pixels will be overwritten 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: Rect Raises: ValueError -- if len(points) < 2 (must have at least 2 points)

-- if (must have at least 2 points) TypeError -- if points is not a sequence or points does not contain number pairs Changed in pygame 2.0.0: Added support for keyword arguments.