【Pygame手册02/20】pygame模块display控制窗口和屏幕

一、说明

   本篇我们介绍pygame的display接口；该接口针对显性窗口的方方面面，在该文中，基本参考了官方手册，保证内容的覆盖，并且，作为代码支援，作者因此做了一些测试代码，和图片动画项目供相关人员参考。

二、pygame.display接口函数

   display是pygame下的接口之一，所谓接口，就是本身无什么功能，但可以通过它调用其它的实质函数。如下图：

2.1 函数表格

2.2 pygame.display的功能

   该模块提供对 pygame 显示的控制。Pygame只有一个显示器 包含在窗口中或全屏运行的 Surface。一旦你 创建您将其视为常规 Surface 的显示器。更改不是 立即在屏幕上可见;您必须选择两个翻转功能之一 以更新实际显示。

   显示的原点，其中 x = 0 和 y = 0，是 屏幕。两个轴都向屏幕右下角正向增加。

   pygame 显示实际上可以在几种模式之一中初始化。由 默认情况下，显示器是基本的软件驱动的帧缓冲。您可以请求 特殊模块，如自动扩展或 OpenGL 支持。这些是 由传递给 的标志控制。pygame.display.set_mode()

   Pygame在任何时候都只能有一个显示器处于活动状态。创建一个新的 with 将关闭上一个显示。检测 附加屏幕的数量和大小，您可以使用，然后选择适当的窗口大小 并显示要传递给 的索引。

pygame.display.set_mode()
pygame.display.get_desktop_sizes
pygame.display.set_mode()
1
2
3

   向后兼容，可精确控制 像素格式或显示分辨率。这曾经是旧的 显卡和 CRT 屏幕，但通常不再需要。使用 函数 、 ，并查询有关显示的详细信息。

pygame.displaypygame.display.mode_ok()
pygame.display.list_modes()
pygame.display.Info()
1
2
3

   创建显示 Surface 后，此模块中的功能会影响 单个现有显示器。如果模块 初始 化。如果设置了新的显示模式，则现有 Surface 将 自动切换以在新显示器上操作。

   设置显示模式后，会在 pygame 事件上放置多个事件 队列。 当用户请求程序时发送 关闭。该窗口将接收事件作为显示 获得和失去输入焦点。如果使用标志设置了显示，则当 用户调整窗口尺寸。直接绘制到硬件显示器 当窗口的某些部分必须 被重新绘制。

pygame.QUIT
pygame.ACTIVEEVENT
pygame.RESIZABLE
pygame.VIDEORESIZE
pygame.VIDEOEXPOSE
1
2
3
4
5

   pygame 2.0.1 中引入了一个新的 windowevent API。查看事件模块文档 了解更多信息

   某些显示环境具有自动拉伸所有选项 窗户。启用此选项后，此自动拉伸会扭曲 pygame 窗口的外观。在 pygame 示例目录中，有 示例代码 （prevent_display_stretching.py） 显示如何禁用此功能 在Microsoft Windows（Vista或更高版本）上自动拉伸pygame显示 必需）。

三、详细的函数调用

   pygame可以理解成总管理程序，或者叫做隐形的总窗口，或者叫主应用，都没有错。

3.1 pygame.display.init()

   初始化显示模块

• init（） -> none

   初始化 pygame 显示模块。如果不执行该指令，显示模块无任何操作功能，什么时候它被初始化，什么时候开始具备操作功能。

   Pygame 会在初始化时从多个内部显示后端之一中进行选择。显示模式将根据平台和当前用户的权限进行选择。在初始化显示模块之前，可以设置环境变量 SDL_VIDEODRIVER 来控制使用哪个后端。这里列出了具有多种选择的系统。

Windows : windib, directx
Unix    : x11, dga, fbcon, directfb, ggi, vgl, svgalib, aalib
1
2

   在某些平台上，可以将 pygame 显示嵌入到已有的窗口中。为此，必须将环境变量 SDL_WINDOWID 设置为包含窗口 ID 或句柄的字符串。初始化 pygame 显示时会检查环境变量。请注意，在嵌入式显示器中运行时可能会出现许多奇怪的副作用。

   多次调用此函数是无害的，重复调用没有效果。

3.2 pygame.display.quit()

   销毁并退出显示模块
quit（） -> none
   这将关闭整个显示模块。这意味着任何活动 显示器将关闭。这也将在 程序退出。

   多次调用是无害的，重复调用没有效果。

3.3 pygame.display.get_init()

   如果显示模块已初始化，则返回 True
get_init（） -> bool
   如果pygame.displaypygame模块控制显示窗口和屏幕模块当前已初始化。

3.4 pygame.display.set_mode()

   初始化要显示的窗口或屏幕

set_mode（size=（0， 0）， flags=0， depth=0， display=0， vsync=0） -> Serface
1

   此函数将创建一个显示 Surface。传入的参数是 对显示类型的请求。实际创建的显示将是最好的 系统支持的可能匹配项。

•    请注意，调用此函数会隐式初始化 ，如果 它以前没有初始化。pygame.display

•    size 参数是一对数字，表示宽度和 高度。flags 参数是附加选项的集合。深度 argument 表示用于颜色的位数。

•    返回的曲面可以像常规曲面一样绘制，但 更改最终将在监视器上看到。

   如果未传递或设置为 size 且 pygame 使用 1.2.10 或更高版本，则创建的 Surface 将具有与 当前屏幕分辨率。如果仅将 width 或 height 设置为(0, 0) ， Surface 的宽度或高度将与屏幕分辨率相同。使用 1.2.10 之前的版本将引发异常。

   通常最好不要传递深度参数。它将默认为 系统的最佳和最快的颜色深度。如果您的游戏需要 可以使用此参数控制深度的特定颜色格式。皮加姆 将模拟不可用的颜色深度，这可能会很慢。

   请求全屏显示模式时，有时与 无法制作请求的大小。在这些情况下，pygame 将选择 最接近的兼容匹配项。返回的曲面仍将始终匹配 请求的大小。

   在高分辨率显示器（4k、1080p）和微型图形游戏（640x480）上 显示得非常小，因此它们无法播放。SCALED 可纵向扩展窗口 给你的。游戏认为这是一个 640x480 的窗口，但实际上它可以更大。 鼠标事件会针对您进行缩放，因此您的游戏不需要这样做。注意 SCALED 被视为实验性 API，将来可能会更改 释放。

•    flags 参数控制所需的显示类型。有 有几种可供选择，您甚至可以使用 按位或运算符（竖线“|”字符）。这是显示 您要选择的标志：

pygame.FULLSCREEN 创建全屏显示
pygame.DOUBLEBUF 仅适用于 OPENGL
pygame.HWSURFACE（在 pygame 2 中已过时）硬件加速，仅在全屏中
pygame.OPENGL 创建 OpenGL 可渲染显示
pygame.RESIZABLE 显示窗口应该足够大
pygame.NOFRAME 显示窗口将没有边框或控件
pygame.SCALED 分辨率取决于桌面尺寸和比例图形
pygame.SHOWN 窗口以可见模式打开（默认）
pygame.HIDDEN 窗口以隐藏模式打开
pygame 2.0.0 的新功能： 和 SCALEDSHOWNHIDDEN

   通过将参数设置为 ，可以得到一个显示 使用垂直同步，但不能保证您一定会获得。仅限请求 对于设置了 OR 标志的调用完全有效，即使使用 那些设置。您获得的内容取决于硬件和驱动程序配置 pygame 正在运行的系统。下面是调用的示例用法 这可能会给你一个带有 vsync 的显示器：
vsync1set_mode()
pygame.OPENGL
pygame.SCALED

set_mode()

flags = pygame.OPENGL | pygame.FULLSCREEN
window_surface = pygame.display.set_mode((1920, 1080), flags, vsync=1)
1
2
3
4

   垂直同步行为被认为是实验性的，可能会在将来的版本中发生变化。

pygame 2.0.0 新功能：vsync

基本示例：

# Open a window on the screen
screen_width=700
screen_height=400
screen=pygame.display.set_mode([screen_width, screen_height])
1
2
3
4

   显示索引表示使用默认显示。如果没有显示 提供了 index 参数，默认显示可以用 环境变量。0

   在 pygame 2.1.3 中更改： pygame 现在确保对此函数的后续调用会清除 窗口变为黑色。在旧版本中，这是一个实现细节 在主要平台上，此功能已通过测试。

3.5 pygame.display.get_surface()

   获取对当前设置的显示图面的引用

get_surface() -> Serface
1

   返回对当前设置的显示 Surface 的引用。如果没有显示模式 已设置，这将返回 None。

3.6 pygame.display.flip()

   将完整显示的 Surface 更新到屏幕。flip本是翻篇之意，每次翻篇后，需要update()显示，这是标配。

flip（）-> none
1

   这将更新整个显示的内容。如果您的显示模式在 pygame 1 上使用标志 pygame.HWSURFACE 和 pygame.DOUBLEBUF，则这将等待垂直回扫并交换表面。

   当使用 pygame.OPENGL 显示模式时，这将执行 gl 缓冲区交换。

3.7 pygame.display.update()

   更新屏幕的某些部分以显示软件

update（rectangle=None） -> none
update（rectangle_list） -> none

   该函数就像用于软件显示的 pygame.display.flip() 的优化版本。它只允许更新屏幕的一部分，而不是整个区域。如果没有传递参数，它会像 pygame.display.flip() 一样更新整个 Surface 区域。

   请注意，调用 display.update(None) 意味着窗口的任何部分都不会更新。而 display.update() 意味着整个窗口都被更新。

   您可以向函数传递单个矩形或一系列矩形。一次传递多个矩形比使用单个或部分矩形列表多次调用更新更有效。如果传递一系列矩形，则可以安全地在列表中包含 None 值，该值将被跳过。

   此调用不能在 pygame.OPENGL 显示上使用，并且会生成异常。

3.8 pygame.display.get_driver()

   获取 pygame 显示后端的名称
get_driver（） ->name
   Pygame 在初始化时选择许多可用的显示后端之一。这将返回用于显示后端的内部名称。这可用于提供有关可以加速哪些显示功能的有限信息。请参阅 pygame.display.set_mode() 中的 SDL_VIDEODRIVER 标志以查看一些常见选项。

3.9 pygame.display. Info()

   创建视频显示信息对象

Info（） -> VideoInfo
1

   创建一个包含多个属性的简单对象来描述当前图形环境。如果在 pygame.display.set_mode() 之前调用此函数，某些平台可以提供有关默认显示模式的信息。这也可以在设置显示模式后调用，以验证特定的显示选项是否得到满足。 VidInfo 对象有几个属性：

• hw: 1 如果显示器是硬件加速的
• wm: 1 如果可以使用窗口显示模式
• video_mem：显示器上的视频内存兆字节。这是 0 如果
  未知
• bitsize：用于存储每个像素的位数
• bytesize：用于存储每个像素的字节数
• mask：用于将 RGBA 值打包为像素的四个值
• shifts：用于将 RGBA 值打包为像素的四个值
• losses：用于将 RGBA 值打包到像素中的四个值
• blit_hw：如果硬件 Surface blitting 加速，则为 1
• blit_hw_CC：如果硬件 Surface colorkey blitting 加速，则为 1
• blit_hw_A：如果硬件 Surface 像素 alpha blitting 加速，则为 1
• blit_sw：如果软件 Surface blitting 加速，则为 1
• blit_sw_CC：如果软件 Surface colorkey blitting 加速，则为 1
• blit_sw_A：如果软件 Surface 像素 alpha blitting 加速，则为 1
• current_h、current_w：当前视频模式的高度和宽度，或者, 如果在 display.set_mode 之前调用，则为桌面的模式。出错时它们为 -1，或者: 正在使用旧的 SDL。

3.10 pygame.display.get_wm_info()

   获取有关当前窗口系统的信息

get_wm_info（） -> dict
1

   创建一个充满字符串键的字典。字符串和值是 由系统任意创建。某些系统可能没有信息，并且 将返回一个空字典。大多数平台都会返回一个“窗口” 键，其值设置为当前显示的系统 ID。

3.11 pygame.display.get_desktop_sizes()

   获取活动桌面的大小

get_desktop_sizes（） ->list
1

   此函数返回当前配置的大小 虚拟桌面作为整数的 （x， y） 元组的列表。

   列表的长度与连接的监视器的数量不同， 因为桌面可以镜像到多个显示器。桌面大小 不要指示硬件支持的最大显示器分辨率， 而是在操作系统中配置的桌面大小。

   为了使窗口适合当前配置的桌面，并尊重操作系统在全屏模式下配置的分辨率，应使用此函数来替换 pygame.display.list_modes() 的许多用例（只要适用）。

3.12 pygame.display.list_modes()

   此函数返回指定颜色深度的可能尺寸列表。如果给定参数没有可用的显示模式，则返回值将为空列表。返回值 -1 意味着任何请求的大小都应该有效（窗口模式可能就是这种情况）。模式大小按从最大到最小的顺序排序。

   如果深度为 0，则使用显示器的当前/最佳颜色深度。标志默认为 pygame.FULLSCREEN，但您可能需要为特定的全屏模式添加其他标志。

   显示索引 0 表示使用默认显示。

   从 pygame 2.0 开始，pygame.display.get_desktop_sizes() 已经接管了 pygame.display.list_modes() 的一些用例：

   要为非全屏窗口找到合适的尺寸，最好使用 pygame.display.get_desktop_sizes() 获取当前桌面的尺寸，然后选择较小的窗口尺寸。这样，即使显示器配置的分辨率低于硬件支持的最大分辨率，也能保证窗口适合。

   为了避免更改物理显示器分辨率，最好使用 pygame.display.get_desktop_sizes() 来确定全屏分辨率。强烈建议开发人员默认使用当前的物理显示器分辨率，除非用户明确请求不同的分辨率（例如在选项菜单或配置文件中）。

3.13 pygame.display.mode_ok()

   为显示模式选择最佳颜色深度

mode_ok（size， flags=0， depth=0， display=0） ->deepth
1

   此函数使用与 相同的参数。它 用于确定请求的显示模式是否可用。它会 如果无法设置显示模式，则返回。否则，它将返回一个 与所要求的显示器最匹配的像素深度。pygame.display.set_mode()0

   通常深度参数不会通过，但有些平台可以支持 多个显示深度。如果通过，它将提示哪个深度更好 火柴。

   如果无法设置传递的显示标志，则该函数将返回。0

   显示索引表示使用默认显示。0

3.14pygame.display.gl_get_attribute()

   获取当前显示的 OpenGL 标志的值

 gl_get_attribute（flag） ->value
1

   用flag调用后， 最好检查任何请求的 OpenGL 属性的值。有关有效标志的列表，请参阅。`

pygame.display.set_mode()
pygame.OPENGL
pygame.display.gl_set_attribute()`
1
2
3

3.15 pygame.display.gl_set_attribute()

   请求显示模式的 OpenGL 显示属性

gl_set_attribute（flag， value） ->none
1

   当使用 pygame.OPENGL 标志调用 pygame.display.set_mode() 时，Pygame 会自动处理颜色和双缓冲等 OpenGL 属性的设置。 OpenGL 提供了您可能想要控制的其他几个属性。传递这些属性之一作为标志及其适当的值。这必须在 pygame.display.set_mode() 之前调用。

   许多设置都是所要求的最小值。如果 OpenGL 无法提供所请求的属性，则使用 OpenGL 上下文创建窗口将会失败，但它可能会为您提供一个模板缓冲区，即使您没有请求任何属性，或者它可能会为您提供一个比请求的更大的模板缓冲区。

   这些flag是：OPENGL

GL_ALPHA_SIZE, GL_DEPTH_SIZE, GL_STENCIL_SIZE, GL_ACCUM_RED_SIZE,
GL_ACCUM_GREEN_SIZE, GL_ACCUM_BLUE_SIZE, GL_ACCUM_ALPHA_SIZE,
GL_MULTISAMPLEBUFFERS, GL_MULTISAMPLESAMPLES, GL_STEREO
GL_MULTISAMPLEBUFFERS

   是否启用多重采样抗锯齿。 默认值为 0（禁用）。

   设置为值 高于 0 以控制抗锯齿量。 典型值为 2 或 3。
GL_MULTISAMPLESAMPLES
GL_STENCIL_SIZE
模具缓冲区的最小位大小。默认值为 0。
GL_DEPTH_SIZE
深度缓冲区的最小位大小。默认值为 16。
GL_STEREO
1 启用立体 3D。默认值为 0。
GL_BUFFER_SIZE

帧缓冲区的最小位大小。默认值为 0。

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

pygame 2.0.0 新功能： 其他属性：

GL_ACCELERATED_VISUAL,
GL_CONTEXT_MAJOR_VERSION, GL_CONTEXT_MINOR_VERSION,
GL_CONTEXT_FLAGS, GL_CONTEXT_PROFILE_MASK,
GL_SHARE_WITH_CURRENT_CONTEXT,
GL_CONTEXT_RELEASE_BEHAVIOR,
GL_FRAMEBUFFER_SRGB_CAPABLE
GL_CONTEXT_PROFILE_MASK
1
2
3
4
5
6
7

将 OpenGL 配置文件设置为以下值之一：

GL_CONTEXT_PROFILE_CORE             disable deprecated features
GL_CONTEXT_PROFILE_COMPATIBILITY    allow deprecated features
GL_CONTEXT_PROFILE_ES               allow only the ES feature
                                    subset of OpenGL
GL_ACCELERATED_VISUAL
1
2
3
4
5

设置为 1 要求硬件加速，设置为 0 强制软件渲染。 默认情况下，两者都是允许的。

3.16 pygame.display.get_active()

   当屏幕上的显示处于活动状态时返回 True

get_active（） -> bool
1

   当显示 Surface 被视为活动时返回 True 可在屏幕上呈现，并且可能对用户可见。这是 紧随其后的默认状态。 即使应用程序完全隐藏，此方法也可能返回 True 在另一个应用程序窗口后面。pygame.display.set_mode()

   如果显示 Surface 已图标化，则返回 False，或者 最小化（通过或通过操作系统） 特定方法，例如大多数上可用的最小化图标 桌面）。

3.17 pygame.display.iconify()

   该方法还可以出于其他原因返回 False，而无需 应用程序被用户显式图标化或最小化。一个 值得注意的例子是，如果用户有多个虚拟桌面和 显示器 Surface 不在活动的虚拟桌面上。

   注意：此函数返回 True 与 应用程序具有输入焦点。请参阅与输入焦点相关的 API。

3.18 pygame.display.iconify()

   图标化显示图面

iconify（） -> bool
1

   请求将显示表面的窗口图标化或隐藏。并非所有系统和显示器都支持图标化显示。如果成功，该函数将返回 True。

   当显示图标化时 pygame.display.get_active() 将返回 False。当窗口被图标化时，事件队列应该接收 ACTIVEEVENT 事件。此外，当窗口在 pygame 2 上图标化时，事件队列还会收到 WINDOWEVENT_MINIMIZED 事件。

3.19 pygame.display.toggle_fullscreen()

   在全屏显示和窗口显示之间切换

toggle_fullscreen（） -> int
1

   在窗口模式和全屏模式之间切换显示窗口。 使用 pygame 1 时，显示驱动程序支持不是很好，但有 PyGame 2 这是在全屏之间切换的最可靠方法。

• pygame 1 中支持的显示驱动程序：

x11 （Linux/Unix）
wayland （Linux/Unix）`
1
2

• pygame 2 中支持的显示驱动程序：

windows （Windows）
x11 （Linux/Unix）
wayland （Linux/Unix）
coco （OSX/Mac）
1
2
3
4

   注意:在 Windows 上不起作用, 除非窗口大小在pygame.display.list_modes()获取可用全屏模式的列表或 flag pygame.SCALED. See issue #2380.窗口是使用标志创建的。

3.20 pygame.display.set_gamma()

   更改硬件伽玛斜坡
set_gamma（红色，绿色=无，蓝色=无） -> bool
已弃用：此功能将在 SDL3 中消失。

在显示硬件上设置红色、绿色和蓝色 Gamma 值。如果 绿色和蓝色参数不会通过，它们都将与红色相同。 并非所有系统和硬件都支持伽玛斜坡（如果功能成功） 它将返回 .True

如果 的 Gamma 值为 ，则创建线性颜色表。较低的值将 使显示屏变暗，值越高，值越高。1.0

自 pygame 2.2.0 起已弃用。
1
2
3
4
5

3.21 pygame.display.set_gamma_ramp()

   通过自定义查找更改硬件 Gamma 斜坡

set_gamma(red, green=None, blue=None) -> bool
1

   自 pygame 2.2.0 起已弃用。
   在显示硬件上设置红色、绿色和蓝色伽玛值。如果绿色和蓝色参数未通过，它们都将与红色相同。并非所有系统和硬件都支持伽玛斜坡，如果该函数成功，它将返回 True。

   1.0 的伽玛值创建线性颜色表。较低的值将使显示变暗，较高的值将使显示变亮。

3.22 pygame.display.set_icon()

   更改显示窗口的系统映像
set_icon（Surface） -> none
   设置系统将用于表示显示窗口的运行时图标。 所有窗口默认为窗口图标的简单 pygame 徽标。

   请注意，调用此函数会隐式初始化 ，如果 它以前没有初始化。pygame.display

   您可以传递任何表面，但大多数系统都希望周围图像较小 32x32. 图像可以具有 colorkey 透明度，该透明度将传递给 系统。

   某些系统不允许窗口图标在显示后进行更改。 这个函数可以先调用来创建 设置显示模式前的图标。pygame.display.set_mode()

3.23 pygame.display.set_caption()

   设置当前窗口标题

set_caption（title， icontitle=None） -> none
1

   如果显示器有窗口标题，此函数将更改窗口上的名称。在 pygame 1.x 中，一些系统支持替代的较短标题用于最小化显示，但在 pygame 2 中 icontitle 不执行任何操作。

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

3.24 pygame.display.get_caption()

   获取当前窗口标题

get_caption（） -> （title， icontitle）
1

   返回显示窗口的标题和图标标题。在 pygame 2.x 中 这些值将始终相同。

3.25 pygame.display.set_palette()

   设置索引显示的显示调色板

set_palette（palette=None） -> none
1

   这将更改 8 位显示器的视频显示调色板。这 不更改实际显示 Surface 的调色板，仅更改调色板 用于显示 Surface。如果未传递 palette 参数，则 系统默认调色板将被恢复。调色板是一系列三胞胎。RGB

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

3.26 pygame.display.get_num_displays()

   返回显示数
get_num_displays（） -> int
   返回可用显示器的数量。如果出现，则始终为 1pygame.get_sdl_version()获取 SDL 的版本号返回低于 2 的主版本号。

   pygame 1.9.5 的新功能。

3.27 pygame.display.get_window_size()

   返回窗口或屏幕的大小
get_window_size（） ->tuple
   返回初始化的窗口的大小pygame.display.set_mode()初始化要显示的窗口或屏幕. 如果使用，这可能与显示表面的大小不同。SCALED

   pygame 2.0.0 的新功能。

3.28 pygame.display.get_allow_screensaver()

   返回是否允许屏幕保护程序运行。
get_allow_screensaver（） -> bool

   返回应用程序运行时是否允许运行屏幕保护程序。默认值为 False。默认情况下，pygame 不允许在游戏过程中使用屏幕保护程序。

   注意 某些平台没有屏幕保护程序或支持禁用屏幕保护程序。请参阅 pygame.display.set_allow_screensaver() 设置屏幕保护程序是否可以运行以获取屏幕保护程序支持的警告。

3.29 pygame.display.set_allow_screensaver()

   设置屏幕保护程序是否可以运行

set_allow_screensaver（bool） -> none
1

   更改应用程序运行时是否允许使用屏幕保护程序。函数参数的默认值为 True。默认情况下，pygame 不允许在游戏过程中使用屏幕保护程序。

   如果屏幕保护程序由于此功能而被禁止，则当调用 pygame.quit()uninitialize 所有 pygame 模块时，它将自动允许运行。

   可以通过环境变量 SDL_HINT_VIDEO_ALLOW_SCREENSAVER 影响默认值，该变量可以设置为 0（禁用）或 1（启用）。

四、后记

   以上将display接口的全部属性项解释一遍l；为了实践和练习上述代码，我做了一些项目，请参阅我的资源：

https://download.csdn.net/download/gongdiwudu/88836913?spm=1001.2014.3001.5501