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

一、说明

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

二、画图函数

2.1 接口draw下的函数

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

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

   大多数函数都采用 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()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

   绘制程序输出结果：