一、说明

   本文对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） – 要绘制的曲面

1. color （Color or int or tuple（int， int， int， [int]）） – 绘制颜色，如果使用 元(RGB[A])

2. points （tuple（coordinate） or list（coordinate）） – 由 3 个或更多个 （x， y） 坐标组成的序列，这些坐标组成 多边形的顶点，序列中的每个坐标必须是 元组/列表/pygame.math.Vector2二维向量2 个整数/浮点数， 例如：[(x1, y1), (x2, y2), (x3, y3)]

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

   绘制程序输出结果：