Pygame/Surface

Language.png本文当前翻译进度约为35%。
The current progress of translating this article is approximately 35%。

目录

pygame.Surface

用于表示图像的 pygame 对象

Surface((width宽度, height高度), flags标志位=0, depth深度=0, masks遮罩=None) → Surface

Surface((width宽度, height高度), flags标志位=0, Surface) → Surface

  • (width, height): 宽度、高度。最高为16383*16383。
  • depth: 深度,可以是8/16/24/32。如果是8位,使用一个对应24位颜色的调色板。如果是32位则带有像素级不透明度。

调用 pygame.Surface() 来创建一个新的 Surface 对象,该对象被创建时全黑(如带有像素级不透明度则为透明)。只有尺寸是必选项,如果未指定其他参数,Surface 的格式将适配屏幕。

未翻译部分

The pixel format can be controlled by passing the bit depth or an existing Surface. The flags argument is a bitmask of additional features for the surface. You can pass any combination of these flags:

HWSURFACE creates the image in video memory SRCALPHA the pixel format will include a per-pixel alpha Both flags are only a request, and may not be possible for all displays and formats.

Advance users can combine a set of bitmasks with a depth value. The masks are a set of 4 integers representing which bits in a pixel will represent each color. Normal Surfaces should not require the masks argument.

Surfaces can have many extra attributes like alpha planes, colorkeys, source rectangle clipping. These functions mainly effect how the Surface is blitted to other Surfaces. The blit routines will attempt to use hardware acceleration when possible, otherwise they will use highly optimized software blitting methods.

There are three types of transparency supported in pygame: colorkeys, surface alphas, and pixel alphas. Surface alphas can be mixed with colorkeys, but an image with per pixel alphas cannot use the other modes. Colorkey transparency makes a single color value transparent. Any pixels matching the colorkey will not be drawn. The surface alpha value is a single value that changes the transparency for the entire image. A surface alpha of 255 is opaque, and a value of 0 is completely transparent.

Per pixel alphas are different because they store a transparency value for every pixel. This allows for the most precise transparency effects, but it also the slowest. Per pixel alphas cannot be mixed with surface alpha and colorkeys.

There is support for pixel access for the Surfaces. Pixel access on hardware surfaces is slow and not recommended. Pixels can be accessed using the get_at() and set_at() functions. These methods are fine for simple access, but will be considerably slow when doing of pixel work with them. If you plan on doing a lot of pixel level work, it is recommended to use a pygame.PixelArraypygame object for direct pixel access of surfaces, which gives an array like view of the surface. For involved mathematical manipulations try the pygame.surfarraypygame module for accessing surface pixel data using array interfaces module (It's quite quick, but requires NumPy.)

Any functions that directly access a surface's pixel data will need that surface to be lock()'ed. These functions can lock() and unlock() the surfaces themselves without assistance. But, if a function will be called many times, there will be a lot of overhead for multiple locking and unlocking of the surface. It is best to lock the surface manually before making the function call many times, and then unlocking when you are finished. All functions that need a locked surface will say so in their docs. Remember to leave the Surface locked only while necessary.

Surface pixels are stored internally as a single number that has all the colors encoded into it. Use the map_rgb() and unmap_rgb() to convert between individual red, green, and blue values into a packed integer for that Surface.

Surface 还可以引用其他 Surface 作为部件,通过 subsurface() 创建。对两者之一的更改会在另一边生效。

每个 Surface 都有一个修剪范围,默认情况下该范围等于整个 Surface,如果其被指定,所有描画操作只对修剪范围生效。

本节原文

pygame.Surface.blit()

将一个图像画到另一个上

blit(source源图像, dest目标位置, area区域=None, special_flags标志位=0) → Rect

  • source: 描画的来源图像。
  • dest: 描画位置,可以是 Rect 或对应描画位置左上角的 (x, y) 元组。必选。
  • area: 从来源图像选择的描画区域。如果未指定则为整张来源图像。
  • special_flags: 标志位,可以是这些选项:BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAX,BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX, BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAX。

pygame.Surface.blits()

将多个图像画到另一个上 (1.9.4+)

(待补充)

pygame.Surface.convert()

转换图像的像素格式

convert(Surface=无) → Surface

convert(depth深度, special_flags标志位=0) → Surface

convert(masks遮罩, special_flags标志位=0) → Surface

创建一个转换过像素格式的 Surface 的副本。新的像素格式可以使用另一个存在的 Surface 的;也可以像调用 pygame.Surface() 一样指定深度、标志和遮罩;如果没有参数,新的 Surface 的像素格式将和显示 Surface 相同,这总是用于描画的最快格式。将频繁描画的 Surface 转换一下是一个好的做法。

转换后的 Surface 不带像素级不透明度,即使原先有,也会被削除;如果你想保留,参见下一个方法。

副本的类型和原图相同;所以该方法一般无需在 Surface 的子类中重写,除非子类有特有的对象属性需要拷贝。

pygame.Surface.convert_alpha()

转换图像的像素格式,包括像素级不透明度

convert_alpha(Surface) → Surface

convert_alpha() → Surface

创建一个转换过像素格式的 Surface 的副本。新 Surface 将为向指定 Surface 描画而优化;如果未指定 Surface,新 Surface 将对当前显示优化。

和 convert() 不同,新图像的像素格式并不总是和指定的 Surface 相同。

副本的类型和原图也是相同的。

pygame.Surface.copy()

创建图像的拷贝

copy() → Surface

创建一个 Surface 的副本;副本的像素格式、调色板、透明度设定和类型和正本相同。

如果 Surface 的子类需要拷贝其特有属性的话,需要重写本方法。

pygame.Surface.fill()

用纯色填充 Surface

fill(color颜色, rect矩形=None, special_flags标志位=0) -> Rect

如果没有矩形被指定,那么整个 Surface 都会被填充。如果被指定,则该矩形与 Surface 修剪范围的交集被填充。

颜色参数可以是 RGB红绿蓝 数组,RGBA红、绿、蓝、不透明度 数组或颜色索引。如果使用 RGBA,但 Surface 不带像素级不透明度,则不透明度被忽略。(Surface 有 SRCALPHA 标志)

pygame.Surface.scroll()

Shift the surface image in place

pygame.Surface.set_colorkey()

设置透明色

(待补充)

pygame.Surface.get_colorkey()

获取当前透明色

(待补充)

pygame.Surface.set_alpha()

设置整个图像透明度

(待补充)

pygame.Surface.get_alpha()

获取整个图像透明度

(待补充)

pygame.Surface.lock()

锁定 Surface 以供像素级访问

lock() → 无

锁定 Surface 的像素数据。对于硬件加速 Surface,像素数据可能会存储在易失性显存中,或以非线性压缩形式储存;当 Surface 被锁定,其像素数据就可以被普通程序访问。写入像素值的代码需要 Surface 处于锁定状态。

在非必要情况下,Surface 不应该保持锁定,被锁定的 Surface 很多时候不能被 pygame 显示或操作。

不是所有 Surface 需要锁定。mustlock() 方法可以检测是否需要。锁定或解锁无需锁定或解锁的 Surface 没有性能惩罚。

所有 pygame 方法会自动按需锁定或解锁 Surface。如果一段代码需要重复锁定和解锁多次,将代码块包裹在锁定与解锁对中会有所帮助。

嵌套锁定或解锁调用是安全的。Surface 只有在最后一层解锁调用才会被解锁。

pygame.Surface.unlock()

解锁 Surface

unlock() → 无

被解锁的 Surface 可以被 pygame 描画或管理。详见上文。

pygame.Surface.mustlock()

检测 Surface 是否必须锁定

mustlock() → 布尔

返回 True 如果 Surface 需要被锁定以访问像素数据。一般来说,纯软件 Surface 不需要锁定。这个方法很少被需要,因为直接锁定 Surface 是安全且没有性能惩罚的。

pygame.Surface.get_locked()

检测 Surface 是否正在被锁定

mustlock() → 布尔

返回 True 如果被锁定。它不会读取锁定层数。

pygame.Surface.get_locks()

读取 Surface 的锁

get_locks() → 元组

返回 Surface 当前存在的锁。

pygame.Surface.get_at()

读取 Surface 的像素点

get_at((x, y)) → Color

返回指定像素的 RGBA 像素值。如果 Surface 没有像素级不透明度,不透明度将始终为255(不透明)。如果指定的位置超出 Surface,则引起 IndexError索引错误

读取或写入像素点对于游戏或实时程序来讲过慢。建议使用 bilt、fill 等一次操作大量像素的方法,或使用 surfarrayPixelArray

该方法会按需临时锁定并解锁 Surface。

在 1.9 版本之后,会返回一个 Color 而不是元组。如果需要元组,请使用 tuple(surf.get_at((x,y)))。这应该只在作为字典的键时有用。

pygame.Surface.set_at()

写入 Surface 的像素点

为单一像素设置 RGBA 或颜色索引。如果 Surface 没有像素级不透明度,则不透明度参数被忽略。 Set the RGBA or mapped integer color value for a single pixel. If the Surface does not have per pixel alphas, the alpha value is ignored. Setting pixels outside the Surface area or outside the Surface clipping will have no effect.

读取或写入像素点对于游戏或实时程序来讲过慢,详见上文。该方法也会按需临时锁定并解锁 Surface。

set_at((x, y), Color) → 无

pygame.Surface.get_at_mapped()

读取映射后的 Surface 的像素点 (1.9.2+)

(待补充)

pygame.Surface.get_palette()

获取8位 Surface 的索引颜色调色板

(待补充)

pygame.Surface.get_palette_at()

获取8位 Surface 的索引颜色调色板中的一项

(待补充)

pygame.Surface.set_palette()

设置8位 Surface 的索引颜色调色板

(待补充)

pygame.Surface.set_palette_at()

设置8位 Surface 的索引颜色调色板中的一项

(待补充)

pygame.Surface.map_rgb()

convert a color into a mapped color value '

pygame.Surface.unmap_rgb()

convert a mapped integer color value into a Color '

pygame.Surface.set_clip()

设置修剪范围

pygame.Surface.get_clip()

读取修剪范围

pygame.Surface.subsurface()

创建一个引用其亲本的新 Surface

pygame.Surface.get_parent()

获取 Surface 的亲本

get_parent() → Surface

如果这不是一个子表面,返回 None。

pygame.Surface.get_abs_parent()

获取 Surface 的顶层亲本

get_abs_parent() → Surface

如果这不是一个子表面,返回自身。

pygame.Surface.get_offset()

获取 Surface 在亲本中的位置

get_offset() → (x, y)

如果这不是一个子表面,返回 (0, 0)。

pygame.Surface.get_abs_offset()

获取 Surface 在顶层亲本中的位置

get_abs_offset() → (x, y)

如果这不是一个子表面,返回 (0, 0)。

pygame.Surface.get_size()

获取 Surface 尺寸

get_size() → (width宽度, height高度)

pygame.Surface.get_width()

获取 Surface 宽度

get_width() → 宽度

pygame.Surface.get_height()

获取 Surface 高度

get_height() → 高度

pygame.Surface.get_rect()

获取 Surface 的矩形区域

(待补充)

pygame.Surface.get_bitsize()

获取每像素的位深度

(待补充)

pygame.Surface.get_bytesize()

获取每像素的字节数

(待补充)

pygame.Surface.get_flags()

get the additional flags used for the Surface

pygame.Surface.get_pitch()

获取每行的字节数

pygame.Surface.get_masks()

the bitmasks needed to convert between a color and a mapped integer

pygame.Surface.set_masks()

set the bitmasks needed to convert between a color and a mapped integer

pygame.Surface.get_shifts()

the bit shifts needed to convert between a color and a mapped integer

pygame.Surface.set_shifts()

sets the bit shifts needed to convert between a color and a mapped integer

pygame.Surface.get_losses()

the significant bits used to convert between a color and a mapped integer

pygame.Surface.get_bounding_rect()

获取可容纳数据的最小矩形

(待补充)

pygame.Surface.get_view()

return a buffer view of the Surface's pixels.

pygame.Surface.get_buffer()

acquires a buffer object for the pixels of the Surface.

pygame.Surface._pixels_address()

像素缓冲区地址

(待补充)

pygame 文档中文翻译
常用ColordisplaydraweventfontimagekeylocalsmixermouseRectSurfacetimemusicpygame
高级cursorsjoystickmaskspritetransformBufferProxyfreetypegfxdrawmidiOverlayPixelArraypixelcopysndarraysurfarraymath
其它cameracdromscraptestssurfarrayversion
链接官网英文文档日文译文