【Pygame手册03/20】用于绘制形状的 pygame 模块

一、说明
二、画图函数
- 2.1 接口draw下的函数
- 2.2 pygame.draw.rect()
- 2.3 pygame.draw.polygon()
- 2.4 pygame.draw.circle()
- 2.5 pygame.draw.ellipse()
- 2.6 pygame.draw.arc()
- 2.7 pygame.draw.line ()
- 2.8 pygame.draw.lines()
- 2.9 pygame.draw.aaline()
- 2.10 pygame.draw.aalines()
三、绘图模块示例

一、说明

本文对pygame的接口draw进行系统介绍。绘制几何图，不同于图像显示，它是严格按照几何坐标进行。本文对九个相关函数进行介绍。方便开发人员查阅。

二、画图函数

2.1 接口draw下的函数

draw用于绘制形状的 pygame 模块。绘出的多数是几何形状。如下表所示：

函数	功能
pygame.draw.rect	绘制矩形
pygame.draw.polygon	绘制多边形
pygame.draw.circle	画一个圆
pygame.draw.ellipse	绘制椭圆
pygame.draw.arc	绘制椭圆弧
pygame.draw.line	画一条直线
pygame.draw.lines	绘制多个连续的直线段
pygame.draw.aaline	绘制一条抗锯齿直线
pygame.draw.aalines	绘制多个连续的直线抗锯齿线段

在曲面上绘制几个简单的形状。这些函数将适用于渲染为任何格式的图面。

大多数函数都采用 width 参数来表示笔画的大小（厚度）围绕形状的边缘。如果传递宽度为 0 的形状将被填充（实心）。

所有绘图功能都遵循曲面的裁剪区域，并将被限制在那个区域。这些函数返回一个矩形，表示已更改像素的边界区域。此边界矩形是“最小值” 包围受影响区域的边界框。

所有绘图函数都接受一个 color 参数，该参数可以是以下格式：

一个pygame.Color用于颜色表示的 pygame 对象对象

颜色表示对象的 pygame.Colorpygame 对象
an (RGB) triplet (tuple/list)
an (RGBA) quadruplet (tuple/list)
已映射到表面像素格式的整数值（请参阅 pygame.Surface.map_rgb()将颜色对象转换为颜色值；反之 pygame.Surface.unmap_rgb()将映射的整数颜色值转换为颜色对象）

颜色的 alpha 值将直接写入曲面（如果表面包含像素 alpha），但绘制函数不会绘制透明。

这些功能会暂时锁定它们正在操作的表面。多通过锁定和解锁曲面，可以加快顺序绘图调用绘制调用周围的对象（请参阅pygame.Surface.lock()锁定 Surface 内存以进行像素访问和pygame.Surface.unlock()从像素访问中解锁 Surface 内存).

注意请参阅pygame.gfxdraw用于绘制形状的 pygame 模块用于替代绘制方法的模块。pygame.draw中。

2.2 pygame.draw.rect()

绘制矩形
rect(surface, color, rect) -> Rect
rect(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
在给定Surface上绘制一个矩形。

参数：
surface （Surface） – 要绘制的曲面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(RGB[A])
rect （Rect） – 要绘制的矩形、位置和尺寸
width （int) – （可选）用于线条粗细或指示矩形将被填充（不要与宽度值混淆的参数）rect

if ，（默认）填充矩形width == 0
if ，用于线条粗细width > 0
if ，则不会绘制任何内容width < 0

在 pygame 2.1.1 中更改：现在，绘制具有宽度的矩形时，可以在 rect 的区域，而不是使用对 draw.lines（）的内部调用，其中一半的宽度溢出到矩形区域之外。
圆角矩形
border_radius （int） – （可选）用于绘制带有圆角的矩形。支持的范围为 [0， min（height， width） / 2]，其中 0 表示矩形没有圆角。
border_top_left_radius （int） – （可选）用于设置左上角的值边境。如果未设置此值，它将使用 border_radius 值。
border_top_right_radius （int） – （可选）用于设置右上角的值边境。如果未设置此值，它将使用 border_radius 值。
border_bottom_left_radius （int） – （可选）用于设置左下角的值边境。如果未设置此值，它将使用 border_radius 值。
border_bottom_right_radius （int) --（可选）用于设置右下角的值边境。如果未设置此值，它将使用 border_radius 值。

如果它将绘制没有圆角的矩形border_radius < 1
如果 Border radii 中的任何一个具有 Value，它将使用 border_radius 的值< 0
如果矩形同一侧的半径之和大于矩形大小，则半径将缩放

返回
一个边界已更改像素的矩形，如果未绘制任何像素 bounding rect 的位置将是给定参数的位置，其宽度和高度将为 0。

返回类型：Rect

注意这pygame.Surface.fill()用纯色填充 Surface方法同样适用于绘图填充矩形，并且可以在某些平台上进行硬件加速。

2.3 pygame.draw.polygon()

绘制多边形
多边形（表面、颜色、点）->矩形
polygon（surface， color， points， width=0） -> rect
在给定曲面上绘制多边形。
参数
surface （Surface） – 要绘制的曲面

color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(RGB[A])
points （tuple（coordinate） or list（coordinate）） – 由 3 个或更多个（x， y）坐标组成的序列，这些坐标组成多边形的顶点，序列中的每个坐标必须是元组/列表/pygame.math.Vector2二维向量2 个整数/浮点数，例如：[(x1, y1), (x2, y2), (x3, y3)]
width （int) – （可选）用于线条粗细或指示要填充的多边形

如果 width == 0，（默认）填充多边形
如果width> 0，则用于线条粗细
如果width< 0，则不会绘制任何内容

注意：使用值时，边线将增长在多边形的原始边界之外。有关更多详细信息边缘线的粗细如何增长，请参阅注释的width> 1widthpygame.draw.line()画一条直线功能。

返回
如果未绘制任何像素 bounding rect 的位置将是参数中第一个点的位置（浮点值将被截断）及其宽度和高度将为 0points

返回类型： Rect

错误给出：

ValueError – 如果（必须至少有 3 个点）len(points) < 3
TypeError – 如果不是序列或不是序列包含数字对pointspoints

注意：对于 aapolygon，请使用 aalines() 且closed=True。

2.4 pygame.draw.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

在给定曲面上绘制一个圆。

参数

surface （Surface） – 要绘制的曲面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(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， intor float）） – 圆的中心点，作为 2 个整数/浮点数的序列，例如：(x, y)
radius （int 或 float） – 圆的半径，从参数测量，如果小于 1，则不会绘制任何内容centerradius
width （int) --（可选）用于线条粗细或指示这个圆圈要被填满

if ，width == 0 （默认）填充圆圈
if ，width > 0 用于线条粗细
if ，width < 0 则不会绘制任何内容
注意 width > 1，边线只会向外增长。

draw_top_right （bool） – （可选）如果设置为 True，则为右上角的圆圈将被绘制
draw_top_left （bool） – （可选）如果设置为 True，则为左上角的圆圈将被绘制
draw_bottom_left （bool） – （可选）如果设置为 True，则为左下角的圆圈将被绘制
draw_bottom_right（bool) --（可选）如果设置为 True，则右下角的圆圈将被绘制

如果任何draw_circle_part为 True，则它将绘制所有具有 True 的圆部分value，否则将绘制整个圆圈。

返回： 一个边界已更改像素的矩形，如果未绘制任何像素 bounding rect 的位置将是参数值（float 值将被截断），其宽度和高度将为 0center

返回类型：Rect

出错提示：

TypeError – if center is not a sequence of two numbers
TypeError – if radius is not a number

在 pygame 2.0.0 中更改：添加了对关键字参数的支持。当半径为 0（坐标处的像素）时，不绘制任何内容用于在半径等于 0 时绘制。参数接受 Floats 和 Vector2。改进了绘图算法，使其看起来更像一个圆。centercenter

在 pygame 2.0.0.dev8 中更改：添加了对绘制圆象限的支持。

2.5 pygame.draw.ellipse()

绘制椭圆
ellipse（surface， color， rect） -> Rect
ellipse（surface， color， rect， width=0） -> Rect
在给定曲面上绘制椭圆。

参数

surface （Surface） – 要绘制的曲面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(RGB[A])
rect （Rect） – 表示椭圆，椭圆将在矩形内居中并有界由它
wodth （int) – （可选）用于线条粗细或指示椭圆将被填充（不要与宽度值混淆的参数）rect

if width == 0, (default) 填充 ellipse
if width > 0, 用所给线画出
if width < 0, 无椭圆被画出

注意使用值时，边线只会增长从参数的原始边界向内。
返回
一个边界已更改像素的矩形，如果未绘制任何像素 bounding rect 的位置将是给定参数的位置，其宽度和高度将为0的rect

返回类型 Rect
在 pygame 2.0.0 中更改：添加了对关键字参数的支持。

2.6 pygame.draw.arc()

绘制椭圆弧
arc（surface， color， rect， start_angle， stop_angle） -> rect
arc（surface， color， rect， start_angle， stop_angle， width=1） -> rect
在给定曲面上绘制椭圆弧。

两个角度参数以弧度给出，表示开始和停止弧的位置。弧线沿逆时针方向绘制的 .start_anglestop_angle

参数
surface （Surface） – 要绘制的表面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(RGB[A])
rect （Rect） – 表示弧将基于的椭圆，椭圆将居中矩形内部
start_angle （float） – 弧弧的起始角度
stop_angle（浮点) --圆弧的停止角弧度
如果，start_angle < stop_angle则将圆弧绘制在逆时针方向从start_angle到stop_angle；
如果，如果 start_angle > stop_angle，tau (tau == 2 * pi) 将被添加到 stop_angle，如果生成的停止角度值大于 start_angle，则适用上述 start_angle < stop_angle 情况，否则不会绘制任何内容。
如果，start_angle == stop_angle ，则不会绘制任何内容

宽度（int) --（可选）用于线条粗细（不要混淆）替换为参数的宽度值）rect

if width == 0，则不会绘制任何内容
if width > 0，（默认值为 1）用于线条粗细
if width < 0，与 width == 0 同
注意使用width值时，边线只会增长从参数的原始边界向内。
返回一个边界已更改像素的矩形，如果未绘制任何像素 bounding rect 的位置将是给定参数的位置，其宽度和高度将为 0rect

返回类型：rect

在 pygame 2.0.0 中更改：添加了对关键字参数的支持。

2.7 pygame.draw.line ()

画一条直线
line（surface， color， start_pos， end_pos） -> rect
line（surface， color， start_pos， end_pos， width=1） -> rect
在给定曲面上绘制一条直线。没有端盖。对于厚线的两端是方形的。

参数

surface （Surface） – 要绘制的面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(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， int or float）） – 线的起始位置，（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， intor float）） – 线的结束位置，（x， y）
width （int) --（可选）用于线粗

if 宽度 >= 1，则用于线条粗细（默认值为 1）
if 宽度< 1，则不会绘制任何内容

注意使用值时，行将按如下方式增长。
对于奇数值，每条线的粗细随width原来的线在中间。
对于偶数值，每条线的粗细随 width 原始线偏离中心（因为没有确切的绘制中心线）。因此，斜率为 < 1 的线（水平）将在原始线（在 y 方向上）。斜率 >= 1 的线（垂直）的右侧将多 1 个粗细的像素原始线（在 x 方向上）。

返回
一个边界已更改像素的矩形，如果未绘制任何像素 bounding rect 的位置将是参数值（float 值将被截断），其宽度和高度将为 0start_pos

返回类型：矩形

错误举出：
TypeError – 如果 or 不是两个数字start_posend_pos
在 pygame 2.0.0 中更改：添加了对关键字参数的支持。

2.8 pygame.draw.lines()

绘制多个连续的直线段
lines(surface, color, closed, points) -> Rect
lines(surface, color, closed, points, width=1) -> Rect
在给定曲面上绘制一系列连续的直线。有无端盖或斜接接头。对于粗线，两端是方形的。用尖角绘制粗线可能会产生不良效果。

参数
surface （Surface） – 要绘制的曲面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(RGB[A])
closed （bool） – 如果在序列中的第一个点和最后一个点Truepoints

points （tuple（coordinate） or list（coordinate）） --点（元组（坐标）或列表（坐标）） - 2个或更多（x，y）坐标的序列，其中序列中的每个坐标必须是元组/列表/pygame.math.Vector2a的二维向量2 个整数/浮点数和相邻坐标将通过线段连接，例如对于点 [(x1, y1), (x2, y2), (x3, y3)] 将从 (x1, y1) 到 (x2, y2) 以及从 (x2, y2) 到 (x3) 绘制一条线段, y3)，此外，如果闭合参数为 True，则会从 (x3, y3) 到 (x1, y1) 绘制另一条线段
width（int) – （可选）用于线粗

如果 width >= 1，则用于线条粗细（默认值为 1）
如果 width< 1，则不会绘制任何内容

**注意：**使用值时，请参阅注释的，详细了解粗线如何生长。
返回：一个包围已更改像素的矩形，如果未绘制任何内容，则边界矩形的位置将是点参数中第一个点的位置（浮点值将被截断），其宽度和高度将为 0

返回类型：rect

错误举出：
if len(points) < 2 （必须至少有 2 个点）
TypeError – 如果点不是序列，或点不包含数字对
在 pygame 2.0.0 中更改：添加了对关键字参数的支持。

2.9 pygame.draw.aaline()

绘制一条抗锯齿直线
aaline（surface， color， start_pos， end_pos） -> Rect
aaline（surface， color， start_pos， end_pos， blend=1） -> Rect
在给定曲面上绘制一条抗锯齿的直线。

线的粗细为 1 像素，端点的高度和每个像素的宽度为一个像素。

线及其端点的绘制方式：

如果两个端点相等，则仅绘制单个像素（之后四舍五入浮点数到最接近的整数）。
否则，如果线不陡峭（即如果沿 x 轴的长度大于沿 y 轴的高度）：
对于每个终结点：如果，端点的 x 坐标是整数 find 哪些像素将被它覆盖并绘制它们。x

否则：用整数计算最近点的位置对于其 x 坐标，当将直线延伸到端点。找出将覆盖哪些像素以及到那时覆盖多少像素。

如果端点是左边的端点，则将覆盖率乘以（1 - 的）的小数部分。x

否则，将覆盖率乘以的小数部分。x

然后绘制这些像素。

例如：
该行的左端点将覆盖 70% 的像素和 30% 的像素，而右侧的像素将覆盖 100% 的像素像素。((1, 1.3), (5, 3))(1, 1)(1, 2)(5, 3)
线的左端点将覆盖 56%（即 0.8 * 70%）的像素和 24%（即 0.8 * 30%）的像素，而正确的一个将覆盖 42%（即 0.6 * 70%）像素和 18%（即 0.6 * 30%）的像素，而右边((1.2, 1.4), (4.6, 3.1))(1, 1)(1, 2)(5, 3)(5, 4)
然后对于端点之间的每个点，沿着这条线，其 x 坐标是一个整数：
找出将覆盖哪些像素以及该点覆盖的像素数量，以及画出来。

例如：
沿线的点将是和将覆盖 50% 的像素、50% 的像素和 100% 的像素。((1, 1), (4, 2.5))(2, 1.5)(3, 2)(2, 1)(2, 2)(3, 2)
沿线的点将 be（覆盖 20% 的像素和 80% 的像素），（覆盖 70% 的像素和 30% 的像素）和（覆盖 20% 的像素和 80% 的像素((1.2, 1.4), (4.6, 3.1))(2, 1.8)(2, 1)(2, 2)(3, 2.3)(3, 2)(3, 3)(4, 2.8)(2, 1)(2, 2))
否则，对陡峭线执行与非陡线相同的操作，但沿 y 轴而不是 x 轴（使用 instead of ，顶部而不是左侧，底部而不是右侧）。yx

注意关于坐标的浮点值，一个具有坐标的点由两个整数组成被认为是正中所述像素（因此具有 1 像素的高度和宽度完全覆盖它），而一个点与坐标，其中一（或两者）的数字具有非零小数部分将部分覆盖两个（如果两个数字都有小数部分，则为四个）相邻像素，例如，该点覆盖了 60% 的像素和 40% 的像素。
参数
surface （Surface） – 要绘制的曲面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(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， int or float）） – 线的起始位置，（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， intor float）） – 线的结束位置，（x， y）
blend （int） – （可选）（已弃用）如果非零（默认）则该行将被混合替换为 Surface 的现有像素阴影，否则将覆盖它们

返回
一个边界已更改像素的矩形，如果未绘制任何像素 bounding rect 的位置将是参数值（float 值将被截断），其宽度和高度将为 0start_pos

返回类型：“矩形

错误举出：
TypeError – 如果 start_pos 或 end_pos不是两个数字。
在 pygame 2.0.0 中更改：添加了对关键字参数的支持。

2.10 pygame.draw.aalines()

绘制多个连续的直线抗锯齿线段
aalines（surface， color， closed， points） -> rect
aalines（surface， color， closed， points， blend=1） -> rect
在给定的表面。

参数
surface （Surface） – 要绘制的曲面
color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用元(RGB[A])
closed （bool） – 如果在序列中的第一个点和最后一个点Truepoints
points （tuple（coordinate） or list（coordinate）） – 点（元组（坐标）或列表（坐标）） - 2个或更多（x，y）坐标的序列，其中序列中的每个坐标必须是元组/列表/pygame.math.Vector2a的二维向量2 个整数/浮点数和相邻坐标将通过线段连接，例如对于点 [(x1, y1), (x2, y2), (x3, y3)] 将从 (x1, y1) 到 (x2, y2) 以及从 (x2, y2) 到 (x3) 绘制一条线段, y3)，此外，如果闭合参数为 True，则会从 (x3, y3) 到 (x1, y1) 绘制另一条线段

blend （int） – （可选）（已弃用）如果非零（默认）每行将被混合替换为表面的现有像素阴影，否则像素将覆盖

返回一个边界已更改像素的矩形，如果未绘制任何像素 bounding rect 的位置将是参数中第一个点的位置（浮点值将被截断）及其宽度和高度将为 0points

返回类型 rect

错误举出：
ValueError – 如果len(points) < 2（必须至少有 2 个点）
TypeError – 如果不是序列points或points不是序列包含数字对
在 pygame 2.0.0 中更改：添加了对关键字参数的支持。

三、绘图模块示例

draw 模块的示例代码。

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 somethingif event.type == pygame.QUIT:  # If user clicked closedone = True  # Flag that we are done so we exit this loop# Clear the screen and set the screen backgroundscreen.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 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 outlinepygame.draw.rect(screen, "black", [75, 10, 50, 20], 2)# Draw a solid rectangle. Same color as "black" above, specified in a new waypygame.draw.rect(screen, (0, 0, 0), [150, 10, 50, 20])# Draw a rectangle with rounded cornerspygame.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 boundariespygame.draw.ellipse(screen, "red", [225, 10, 50, 20], 2)# Draw an solid ellipse, using a rectangle as the outside boundariespygame.draw.ellipse(screen, "red", [300, 10, 50, 20])# This draws a triangle using the polygon commandpygame.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 circlepygame.draw.circle(screen, "blue", [60, 250], 40)# Draw only one circle quadrantpygame.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()