pygame object for representing images

Surface((width, height), flags=0, depth=0, masks=None) → Surface

Surface((width, height), flags=0, Surface) → Surface

pygame Surface 用于表示任何图像。 Surface 具有固定的分辨率和像素格式。具有 8 位像素的表面使用调色板映射到 24 位颜色。

调用 pygame.Surface() 创建一个新的图像对象。 Surface 将被清除为全黑。唯一需要的参数是大小。在没有其他参数的情况下，Surface 将以最匹配显示 Surface 的格式创建。

可以通过传递位深度或现有 Surface 来控制像素格式。 flags 参数是表面附加特征的位掩码。您可以传递这些标志的任意组合：

HWSURFACE（在 pygame 2 中已过时）在显存中创建图像 SRCALPHA 像素格式将包括像素级的 alpha 这两个标志只是一个请求，可能不适用于所有显示和格式。

高级用户可以将一组位掩码与深度值结合起来。掩码是一组 4 个整数，表示像素中的哪些位将代表每种颜色。法线表面不应需要 mask 参数。

表面可以有许多额外的属性，如 alpha 平面、颜色键、源矩形剪裁。这些函数主要影响 Surface 如何被 blitted 到其他 Surface。 blit 例程将尽可能尝试使用硬件加速，否则它们将使用高度优化的软件 blitting 方法。

pygame 支持三种类型的透明度：colorkeys、surface alphas 和 pixel alphas。表面 alpha 可以与 colorkeys 混合，但具有每像素 alpha 的图像不能使用其他模式。 Colorkey 透明度使单个颜色值透明。任何与颜色键匹配的像素都不会被绘制。表面 alpha 值是改变整个图像透明度的单个值。表面 alpha 为 255 是不透明的，值为 0 是完全透明的。

每个像素的 alpha 是不同的，因为它们为每个像素存储一个透明度值。这允许最精确的透明效果，但它也是最慢的。每像素 alpha 不能与表面 alpha 和颜色键混合。

Surface 支持像素访问。硬件 Surface 上的像素访问速度很慢，不推荐使用。可以使用 get_at() 和 set_at() 函数访问像素。这些方法适用于简单访问，但在使用它们进行像素工作时会相当慢。如果你打算做很多像素级的工作，建议使用 pygame.PixelArray 对象来直接访问表面的像素，它提供了一个类似数组的表面视图。对于涉及的数学操作，请尝试使用数组接口模块访问表面像素数据的 pygame.surfarray 模块（它非常快，但需要 NumPy）。

任何直接访问 Surface 像素数据的函数都需要对该表面进行锁定。这些函数可以在没有帮助的情况下自行 lock() 和 unlock()，但是，如果一个函数会被多次调用，那么 Surface 的多次锁定和解锁就会有很多开销。最好在多次调用函数之前手动锁定，完成后再解锁。所有需要锁定 Surface 的功能都会在它们的文档中说明。请记住，仅在必要时才将 Surface 锁定。

Surface 像素在内部存储为单个数字，其中包含所有颜色的编码。使用 map_rgb() 和 unmap_rgb() 将单个红色、绿色和蓝色值转换为该 Surface 的打包整数。

Surface 也可以参考其他 Surface 的片段。这些是使用 subsurface() 方法创建的。对任一 Surface 的任何更改都会影响另一个。

每个 Surface 都包含一个剪辑区域。默认情况下，剪辑区域覆盖整个 Surface。如果更改，所有绘图操作将只影响较小的区域。

将一个图像绘制到另一个图像上

blit(source, dest, area=None, special_flags=0) → Rect

将源 Surface 绘制到此 Surface 上。draw 可以用 dest 参数定位。dest 参数可以是一对表示 blit 左上角位置的坐标，也可以是一个 Rect，其中矩形的左上角将用作 blit 的位置。目标矩形的大小不影响 blit。

也可以传递一个可选的区域矩形。这表示要绘制的源表面的一小部分。

pygame 1.8 中的新功能：可选的 special_flags：BLEND_ADD、BLEND_SUB、BLEND_MULT、BLEND_MIN、BLEND_MAX。

pygame 1.8.1 中的新功能：可选的 special_flags：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 1.9.2 中的新功能：可选的 special_flags：BLEND_PREMULTIPLIED

pygame 2.0.0 中的新功能：可选的 special_flags：BLEND_ALPHA_SDL2 - 使用 SDL2 blitter 进行 alpha 混合，这给出了与默认 blitter 不同的结果，默认 blitter 是在 SDL1 之后建模的，因为 alpha 混合公式使用了不同的近似值。 SDL2 blitter 还支持 alpha 混合表面上的 RLE，而 pygame 则不支持。

返回矩形是受影响像素的区域，不包括目标表面之外或剪辑区域之外的任何像素。

当 blit 到 8 位表面时，像素 alpha 将被忽略。

对于具有 colorkey 或 blanket alpha 的表面，对 self 的 blit 可能会给出与非 self blit 略有不同的颜色。

将许多图像绘制到另一个图像上

blits(blit_sequence=((source, dest), …), doreturn=1) → [Rect, …] or None

blits(((source, dest, area), …)) → [Rect, …]

blits(((source, dest, area, special_flags), …)) → [Rect, …]

在此 Surface 上绘制许多表面。它以一个序列作为输入，每个元素对应于 blit() 的元素。它至少需要一个序列 (source, dest)。

参数

blit_sequence – 一系列表面和 blit 它们的参数，它们对应于 blit() 参数

doreturn – 如果为 True，返回更改区域的列表，否则返回 None

返回值（列表或 None）

如果 doreturn 为 True，则更改区域的矩形列表，否则为 None

pygame 1.9.4 中的新功能。

更改图像的像素格式

convert(Surface=None) → Surface

convert(depth, flags=0) → Surface

convert(masks, flags=0) → Surface

使用更改的像素格式创建 Surface 的新副本。 可以从另一个现有的 Surface 确定新的像素格式。 否则可以使用深度、标志和掩码参数，类似于用于表示图像调用的 pygame.Surface()pygame 对象。

如果未传递任何参数，则新 Surface 将具有与显示 Surface 相同的像素格式。 这始终是最快的 blitting 格式。 最好在所有表面被块化多次之前转换所有表面。

转换后的 Surface 将没有像素 alpha。 如果原件有它们，它们将被剥离。 请参阅 convert_alpha() 以保留或创建每像素 alpha。

新副本将与复制的曲面具有相同的类。 这让 Surface 子类无需重写即可继承此方法，除非子类特定的实例属性也需要复制。

更改图像的像素格式，包括每个像素的 alpha（即不透明度）

convert_alpha(Surface) → Surface

convert_alpha() → Surface

使用所需的像素格式创建表面的新副本。新表面的格式适合于使用每像素 alpha 快速转换为给定格式。如果没有给出表面，新的表面将被优化为 blitting 到当前显示。

与 convert() 方法不同，新图像的像素格式不会与请求的源完全相同，但会针对到目标的快速 alpha blitting 进行优化。

与 convert() 一样，返回的表面与转换后的表面具有相同的类。

create a new copy of a Surface copy() → Surface Makes a duplicate copy of a Surface. The new surface will have the same pixel formats, color palettes, transparency settings, and class as the original. If a Surface subclass also needs to copy any instance specific attributes then it should override copy().

用纯色填充表面

fill(color, rect=None, special_flags=0) → Rect

用纯色填充表面。如果没有给出 rect 参数，整个 Surface 将被填充。rect 参数将填充限制在特定区域。填充也将包含在表面剪辑区域中。

颜色参数可以是 RGB 序列、RGBA 序列或映射颜色索引。如果使用 RGBA，Alpha（RGBA 的一部分）将被忽略，除非表面使用每像素 alpha（表面具有 SRCALPHA 标志）。

pygame 1.8 中的新功能：可选的 special_flags：BLEND_ADD、BLEND_SUB、BLEND_MULT、BLEND_MIN、BLEND_MAX。

pygame 1.8.1 中的新功能：可选的 special_flags：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。

这将返回受影响的 Surface area.

Shift the surface image in place scroll(dx=0, dy=0) → None Move the image by dx pixels right and dy pixels down. dx and dy may be negative for left and up scrolls respectively. Areas of the surface that are not overwritten retain their original pixel values. Scrolling is contained by the Surface clip area. It is safe to have dx and dy values that exceed the surface size.

New in pygame 1.9.

设置透明色

set_colorkey(Color, flags=0) → None

set_colorkey(None) → None

设置 Surface 的当前透明色。 将此 Surface 位图 blitting 到目标时，任何与透明色颜色相同的像素都将是透明的。颜色可以是 RGB 颜色或映射颜色整数。如果没有指定，透明色将被取消。

如果 Surface 被格式化为使用每像素 alpha 值，则 colorkey 将被忽略。colorkey 可以与完整的 Surface alpha 值混合。

可选的 flags 参数可以设置为 pygame.RLEACCEL 以在非加速显示上提供更好的性能。RLEACCEL Surface 的修改速度较慢，但作为源 blit 速度更快。

Get the current transparent colorkey get_colorkey() → RGB or None Return the current colorkey value for the Surface. If the colorkey is not set then None is returned.

设置整个 Surface 的 alpha 值

set_alpha(value, flags=0) → None

set_alpha(None) → None

设置 Surface 的当前 alpha 值（即不透明度）。将此 Surface 块化到目的地时，像素将被绘制为略微透明。alpha 值是 0 到 255 之间的整数，0 为完全透明，255 为完全不透明。如果没有为 alpha 值传递，则将禁用 alpha 混合，包括每像素 alpha。

此值不同于像素级表面 alpha。对于具有每像素 alpha 的表面，将忽略 blanket alpha 并返回 None。

在 pygame 2.0 中更改：每表面 alpha 可以与每像素 alpha 结合。

可选的 flags 参数可以设置为 pygame.RLEACCEL 以在非加速显示上提供更好的性能。RLEACCEL Surface 的修改速度较慢，但作为源 blit 速度更快。

get the current Surface transparency value get_alpha() → int_value Return the current alpha value for the Surface.

lock the Surface memory for pixel access lock() → None Lock the pixel data of a Surface for access. On accelerated Surfaces, the pixel data may be stored in volatile video memory or nonlinear compressed forms. When a Surface is locked the pixel memory becomes available to access by regular software. Code that reads or writes pixel values will need the Surface to be locked.

Surfaces should not remain locked for more than necessary. A locked Surface can often not be displayed or managed by pygame.

Not all Surfaces require locking. The mustlock() method can determine if it is actually required. There is no performance penalty for locking and unlocking a Surface that does not need it.

All pygame functions will automatically lock and unlock the Surface data as needed. If a section of code is going to make calls that will repeatedly lock and unlock the Surface many times, it can be helpful to wrap the block inside a lock and unlock pair.

It is safe to nest locking and unlocking calls. The surface will only be unlocked after the final lock is released.

unlock the Surface memory from pixel access unlock() → None Unlock the Surface pixel data after it has been locked. The unlocked Surface can once again be drawn and managed by pygame. See the lock() documentation for more details.

All pygame functions will automatically lock and unlock the Surface data as needed. If a section of code is going to make calls that will repeatedly lock and unlock the Surface many times, it can be helpful to wrap the block inside a lock and unlock pair.

It is safe to nest locking and unlocking calls. The surface will only be unlocked after the final lock is released.

test if the Surface requires locking mustlock() → bool Returns True if the Surface is required to be locked to access pixel data. Usually pure software Surfaces do not require locking. This method is rarely needed, since it is safe and quickest to just lock all Surfaces as needed.

All pygame functions will automatically lock and unlock the Surface data as needed. If a section of code is going to make calls that will repeatedly lock and unlock the Surface many times, it can be helpful to wrap the block inside a lock and unlock pair.

test if the Surface is current locked get_locked() → bool Returns True when the Surface is locked. It doesn't matter how many times the Surface is locked.

Gets the locks for the Surface get_locks() → tuple Returns the currently existing locks for the Surface.

get the color value at a single pixel get_at((x, y)) → Color Return a copy of the RGBA Color value at the given pixel. If the Surface has no per pixel alpha, then the alpha value will always be 255 (opaque). If the pixel position is outside the area of the Surface an IndexError exception will be raised.

Getting and setting pixels one at a time is generally too slow to be used in a game or realtime situation. It is better to use methods which operate on many pixels at a time like with the blit, fill and draw methods - or by using pygame.surfarraypygame module for accessing surface pixel data using array interfaces/pygame.PixelArraypygame object for direct pixel access of surfaces.

This function will temporarily lock and unlock the Surface as needed.

New in pygame 1.9: Returning a Color instead of tuple. Use tuple(surf.get_at((x,y))) if you want a tuple, and not a Color. This should only matter if you want to use the color as a key in a dict.

set the color value for a single pixel set_at((x, y), Color) → None 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.

Getting and setting pixels one at a time is generally too slow to be used in a game or realtime situation.

This function will temporarily lock and unlock the Surface as needed.

Note If the surface is palettized, the pixel color will be set to the most similar color in the palette.

get the mapped color value at a single pixel get_at_mapped((x, y)) → Color Return the integer value of the given pixel. If the pixel position is outside the area of the Surface an IndexError exception will be raised.

This method is intended for pygame unit testing. It unlikely has any use in an application.

This function will temporarily lock and unlock the Surface as needed.

New in pygame 1.9.2.

get the color index palette for an 8-bit Surface get_palette() → [RGB, RGB, RGB, …] Return a list of up to 256 color elements that represent the indexed colors used in an 8-bit Surface. The returned list is a copy of the palette, and changes will have no effect on the Surface.

Returning a list of Color(with length 3) instances instead of tuples.

New in pygame 1.9.

get the color for a single entry in a palette get_palette_at(index) → RGB Returns the red, green, and blue color values for a single index in a Surface palette. The index should be a value from 0 to 255.

New in pygame 1.9: Returning Color(with length 3) instance instead of a tuple.

set the color palette for an 8-bit Surface set_palette([RGB, RGB, RGB, …]) → None Set the full palette for an 8-bit Surface. This will replace the colors in the existing palette. A partial palette can be passed and only the first colors in the original palette will be changed.

This function has no effect on a Surface with more than 8-bits per pixel.

set the color for a single index in an 8-bit Surface palette set_palette_at(index, RGB) → None Set the palette value for a single entry in a Surface palette. The index should be a value from 0 to 255.

This function has no effect on a Surface with more than 8-bits per pixel.

convert a color into a mapped color value map_rgb(Color) → mapped_int Convert an RGBA color into the mapped integer value for this Surface. The returned integer will contain no more bits than the bit depth of the Surface. Mapped color values are not often used inside pygame, but can be passed to most functions that require a Surface and a color.

See the Surface object documentation for more information about colors and pixel formats.

convert a mapped integer color value into a Color unmap_rgb(mapped_int) → Color Convert an mapped integer color into the RGB color components for this Surface. Mapped color values are not often used inside pygame, but can be passed to most functions that require a Surface and a color.

See the Surface object documentation for more information about colors and pixel formats.

set the current clipping area of the Surface set_clip(rect) → None set_clip(None) → None Each Surface has an active clipping area. This is a rectangle that represents the only pixels on the Surface that can be modified. If None is passed for the rectangle the full Surface will be available for changes.

The clipping area is always restricted to the area of the Surface itself. If the clip rectangle is too large it will be shrunk to fit inside the Surface.

get the current clipping area of the Surface get_clip() → Rect Return a rectangle of the current clipping area. The Surface will always return a valid rectangle that will never be outside the bounds of the image. If the Surface has had None set for the clipping area, the Surface will return a rectangle with the full area of the Surface.

create a new surface that references its parent subsurface(Rect) → Surface Returns a new Surface that shares its pixels with its new parent. The new Surface is considered a child of the original. Modifications to either Surface pixels will effect each other. Surface information like clipping area and color keys are unique to each Surface.

The new Surface will inherit the palette, color key, and alpha settings from its parent.

It is possible to have any number of subsurfaces and subsubsurfaces on the parent. It is also possible to subsurface the display Surface if the display mode is not hardware accelerated.

See get_offset() and get_parent() to learn more about the state of a subsurface.

A subsurface will have the same class as the parent surface.

find the parent of a subsurface get_parent() → Surface Returns the parent Surface of a subsurface. If this is not a subsurface then None will be returned.

find the top level parent of a subsurface get_abs_parent() → Surface Returns the parent Surface of a subsurface. If this is not a subsurface then this surface will be returned.

find the position of a child subsurface inside a parent get_offset() → (x, y) Get the offset position of a child subsurface inside of a parent. If the Surface is not a subsurface this will return (0, 0).

find the absolute position of a child subsurface inside its top level parent get_abs_offset() → (x, y) Get the offset position of a child subsurface inside of its top level parent Surface. If the Surface is not a subsurface this will return (0, 0).

获取 Surface 的尺寸

get_size() → (width, height)

以像素为单位返回 Surface 的宽度和高度。

get the width of the Surface get_width() → width Return the width of the Surface in pixels.

get the height of the Surface get_height() → height Return the height of the Surface in pixels.

get the rectangular area of the Surface get_rect(kwargs) → Rect Returns a new rectangle covering the entire surface. This rectangle will always start at (0, 0) with a width and height the same size as the image. You can pass keyword argument values to this function. These named values will be applied to the attributes of the Rect before it is returned. An example would be mysurf.get_rect(center=(100, 100)) to create a rectangle for the Surface centered at a given position. ====get_bitsize()==== get the bit depth of the Surface pixel format get_bitsize() → int Returns the number of bits used to represent each pixel. This value may not exactly fill the number of bytes used per pixel. For example a 15 bit Surface still requires a full 2 bytes. ====get_bytesize()==== get the bytes used per Surface pixel get_bytesize() → int Return the number of bytes used per pixel. ====get_flags()==== get the additional flags used for the Surface get_flags() → int Returns a set of current Surface features. Each feature is a bit in the flags bitmask. Typical flags are RLEACCEL, SRCALPHA, and SRCCOLORKEY. Here is a more complete list of flags. A full list can be found in SDL_video.h SWSURFACE 0x00000000 # Surface is in system memory HWSURFACE 0x00000001 # (obsolete in pygame 2) Surface is in video memory ASYNCBLIT 0x00000004 # (obsolete in pygame 2) Use asynchronous blits if possible See pygame.display.set_mode()Initialize a window or screen for display for flags exclusive to the display surface. Used internally (read-only) HWACCEL 0x00000100 # Blit uses hardware acceleration SRCCOLORKEY 0x00001000 # Blit uses a source color key RLEACCELOK 0x00002000 # Private flag RLEACCEL 0x00004000 # Surface is RLE encoded SRCALPHA 0x00010000 # Blit uses source alpha blending PREALLOC 0x01000000 # Surface uses preallocated memory ====get_pitch()==== get the number of bytes used per Surface row get_pitch() → int Return the number of bytes separating each row in the Surface. Surfaces in video memory are not always linearly packed. Subsurfaces will also have a larger pitch than their real width. This value is not needed for normal pygame usage. ====get_masks()==== the bitmasks needed to convert between a color and a mapped integer get_masks() → (R, G, B, A) Returns the bitmasks used to isolate each color in a mapped integer. This value is not needed for normal pygame usage. ====set_masks()==== set the bitmasks needed to convert between a color and a mapped integer set_masks((r,g,b,a)) → None This is not needed for normal pygame usage. Note In SDL2, the masks are read-only and accordingly this method will raise an AttributeError if called. New in pygame 1.8.1. ====get_shifts()==== the bit shifts needed to convert between a color and a mapped integer get_shifts() → (R, G, B, A) Returns the pixel shifts need to convert between each color and a mapped integer. This value is not needed for normal pygame usage. ====set_shifts()==== sets the bit shifts needed to convert between a color and a mapped integer set_shifts(**(r,g,b,a)) → None This is not needed for normal pygame usage.

Note In SDL2, the shifts are read-only and accordingly this method will raise an AttributeError if called. New in pygame 1.8.1.

the significant bits used to convert between a color and a mapped integer get_losses() → (R, G, B, A) Return the least significant number of bits stripped from each color in a mapped integer.

This value is not needed for normal pygame usage.

find the smallest rect containing data get_bounding_rect(min_alpha = 1) → Rect Returns the smallest rectangular region that contains all the pixels in the surface that have an alpha value greater than or equal to the minimum alpha value.

This function will temporarily lock and unlock the Surface as needed.

New in pygame 1.8.

return a buffer view of the Surface's pixels. get_view(<kind>='2') → BufferProxy Return an object which exports a surface's internal pixel buffer as a C level array struct, Python level array interface or a C level buffer interface. The new buffer protocol is supported.

The kind argument is the length 1 string '0', '1', '2', '3', 'r', 'g', 'b', or 'a'. The letters are case insensitive; 'A' will work as well. The argument can be either a Unicode or byte (char) string. The default is '2'.

'0' returns a contiguous unstructured bytes view. No surface shape information is given. A ValueError is raised if the surface's pixels are discontinuous.

'1' returns a (surface-width * surface-height) array of continuous pixels. A ValueError is raised if the surface pixels are discontinuous.

'2' returns a (surface-width, surface-height) array of raw pixels. The pixels are surface-bytesize-d unsigned integers. The pixel format is surface specific. The 3 byte unsigned integers of 24 bit surfaces are unlikely accepted by anything other than other pygame functions.

'3' returns a (surface-width, surface-height, 3) array of RGB color components. Each of the red, green, and blue components are unsigned bytes. Only 24-bit and 32-bit surfaces are supported. The color components must be in either RGB or BGR order within the pixel.

'r' for red, 'g' for green, 'b' for blue, and 'a' for alpha return a (surface-width, surface-height) view of a single color component within a surface: a color plane. Color components are unsigned bytes. Both 24-bit and 32-bit surfaces support 'r', 'g', and 'b'. Only 32-bit surfaces with SRCALPHA support 'a'.

The surface is locked only when an exposed interface is accessed. For new buffer interface accesses, the surface is unlocked once the last buffer view is released. For array interface and old buffer interface accesses, the surface remains locked until the BufferProxy object is released.

New in pygame 1.9.2.

acquires a buffer object for the pixels of the Surface. get_buffer() → BufferProxy Return a buffer object for the pixels of the Surface. The buffer can be used for direct pixel access and manipulation. Surface pixel data is represented as an unstructured block of memory, with a start address and length in bytes. The data need not be contiguous. Any gaps are included in the length, but otherwise ignored.

This method implicitly locks the Surface. The lock will be released when the returned pygame.BufferProxypygame object to export a surface buffer through an array protocol object is garbage collected.

New in pygame 1.8.

pixel buffer address _pixels_address → int The starting address of the surface's raw pixel bytes.

New in pygame 1.9.2.