pygame中Surface对象的方法详解

将 source 参数指定的 Surface 对象绘制到该对象上。dest 参数指定绘制的位置，dest 的值可以是 source 的左上角坐标。如果传入一个 Rect 对象给 dest，那么 blit() 会使用它的左上角坐标，而与 Rect 的大小无关。
可选参数 area 是一个 Rect 对象，表示限定 source 指定的 Surface 对象的范围。
可选参数 special_flags 是 Pygame 1.8.0 新增的内容，用于指定混合的模式：BLEND_ADD，BLEND_SUB，BLEND_MULT，BLEND_MIN，BLEND_MAX；1.8.1 增加：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；将来还可能添加更多新的标志。
返回值是一个 Rect 对象，表示实际绘制的矩形区域。

注意：

当绘制到一个 8 位的 Surface 对象上时，pixel alphas 会被忽略。
通过 colorkeys 和 surface alphas 设置透明度的 Surface 对象，通过 blit() 绘制自身可能会导致颜色有少许不同。

convert()

功能：修改图像（Surface 对象）的像素格式。

属性：

convert(Surface) -> Surface
convert(depth, flags=0) -> Surface
convert(masks, flags=0) -> Surface
convert() -> Surface

创建一个新的 Surface 对象并返回，可以定制该对象的像素格式。新的像素格式可以从其他已存在的 Surface 对象中获取。另外，depth，flags，masks 参数的使用跟调用 Surface() 相似。
如果没有传入任何参数，那么创建一个相同像素格式的 Surface 对象。
如果原来包含 alpha 通道（小甲鱼温馨提示：即 pixel alphas，见前边讲的透明度控制部分）的 Surface 对象，那么转换后（新创建）的 Surface 对象将不会保留。如果需要保留 alpha 通道，请使用 convert_alpha() 方法。

注意：为了让 pygame 可以更快的处理图像绘制，请加载一个图像（不带透明）后立刻使用 convert() 对其像素格式进行转换。

convert_alpha()

功能：修改图像（Surface 对象）的像素格式，包含 alpha 通道（小甲鱼温馨提示：即 pixel alphas，见前边讲的透明度控制部分）。

属性：

convert_alpha(Surface) -> Surface
convert_alpha() -> Surface

创建一个新的 Surface 对象并返回，可以定制该对象的像素格式。新的像素格式可以从其他已存在的 Surface 对象中获取。另外，depth，flags，masks 参数的使用跟调用 Surface() 相似。
与 convert() 方法不同，convert_alpha() 转换后的 Surface 对象将专门为 alpha 通道做优化，使其可以更快的进行绘制。

注意：为了让 pygame 可以更快的处理图像绘制，请加载一个图像（带透明）后立刻使用 convert_alpha() 对其像素格式进行转换。

copy()

功能：创建一个 Surface 对象的拷贝。

属性：copy() -> Surface

对当前 Surface 对象进行拷贝，返回的 Surface 对象拥有相同的像素格式、调色板和透明度设置。

fill()

功能：使用纯色填充 Surface 对象。

属性：fill(color, rect=None, special_flags=0) -> Rect

默认情况下使用纯色填充整个 Surface 对象。rect 参数可以限制填充的矩形范围，color 参数可以是 RGB 序列、RGBA 序列和映射的颜色索引号。如果使用 RGBA，则只有当 Surface 对象使用 pixel alphas，alpha 通道才会被填充。
可选参数 special_flags 是 Pygame 1.8.0 新增加的内容，用于指定混合的模式：BLEND_ADD，BLEND_SUB，BLEND_MULT，BLEND_MIN，BLEND_MAX；1.8.1 增加：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；将来还可能添加更多新的标志。
返回值是一个 Rect 对象，表示实际绘制的矩形区域。

提示：RGB即三原色 R（Red），G（Green）和 B（Blue），它们每个颜色的值为 0 ~ 255，通过不同程度的混合可以得到非常多的其他颜色。RGBA 其实就是在三原色的基础上添加一个 A（alpha）通道，用于控制每个像素的透明度，范围依然是 0 ~ 255。

scroll()

功能：移动 Surface 对象。

属性：scroll(dx=0, dy=0) -> None

dx 和 dy 参数分别控制水平和垂直位置的偏移量，值为正表示向右（向下），为负表示向左（向上）偏移。没有被覆盖的范围则保留原来的像素值。Surface 对象的剪切范围将影响移动后的结果。当 dx 和 dy 参数的值大于 Surface 对象的尺寸，你将看不到移动的结果，但并不会出错。
所谓的“移动”并不是简单的移动图像到一个新的位置：向右、向下移动 20 像素 2 次后的结果：

set_colorkey()

功能：设置 colorkeys。

属性：

set_colorkey(Color, flags=0) -> None
set_colorkey(None) -> None

设置当前 Surface 对象的 colorkeys，当绘制 Surface 对象时，将所有与 colorkeys 相同的颜色值绘制为透明。 Color 参数可以是 RGB 颜色，也可以是映射后的颜色索引号，如果传入 None，则取消 colorkeys 的设置。
如果 Surface 对象使用的是 pixel alphas 的方式设置透明度，那么 colorkeys 会被忽略（二者不能兼容）；如果 Surface 对象使用 surface alphas 方式设置透明度，那么二者可以混合设置。
可选参数 flags 可以设置为 pygame.RLEACCEL，提供非加速显示的情况下更好的性能。修改一个设置了 RLEACCEL 的 Surface 对象会变慢一些，但绘制到其他 Surface 对象上时会更快。

get_colorkey()

功能：获取当前的 colorkeys。

属性：get_colorkey() -> RGB or None

返回 Surface 对象当前 colorkeys 的颜色值，如果没有设置 colorkeys，则返回 None。

set_alpha()

功能：设置整个图像的透明度。

属性：

set_alpha(value, flags=0) -> None
set_alpha(None) -> None

设置 Surface 对象的整体透明度（surface alpha），value 参数的范围是 0 ~ 255，0 表示完全透明，255 表示完全不透明。如果传入 None，那么取消 surface alphas 设置。
如果 Surface 对象使用的是 pixel alphas 的方式设置透明度，那么 surface alphas 会被忽略（二者不能兼容）；如果 Surface 对象使用 colorkeys 方式设置透明度，那么二者可以混合设置。
可选参数 flags 可以设置为 pygame.RLEACCEL，提供非加速显示的情况下更好的性能。修改一个设置了 RLEACCEL 的 Surface 对象会变慢一些，但绘制到其他 Surface 对象上时会更快。

注意：如果参数传入 None，pixel alphas 设置透明度的方式也会失效。

get_alpha()

功能：获取整个图像的透明度。

属性：get_alpha() -> int_value or None

返回 Surface 对象当前的整体透明度，如果没有设置 surface alpha，则返回 None。

lock()

功能：锁定 Surface 对象的内存使其可以进行像素访问。

属性：lock() -> None

锁定 Surface 的像素数据使得其可以访问。对于加速的 Surface 对象，像素数据可能存储在显存中或以非线性压缩的形式存储。当一个 Surface 对象锁定了像素内存，常规软件就可以对它进行访问。对 Surface 对象进行读取或写入需要将其先锁定。
一般情况下，不应该将 Surface 对象长期保持锁定状态。因为一旦 Surface 对象被锁定，常常无法进行绘制或者导致 Pygame 无法对其进行管理。
另外，并不是所有的 Surface 对象都需要锁定后才能访问。mustlock() 方法可以检测一个 Surface 对象是否确实需要锁定。对于有必要进行锁定和解锁的 Surface 对象，该过程并不会导致任何性能下降。
所有的 Pygame 函数在需要的时候都会自动锁定和解锁 Surface 对象。如果有部分代码需要反复锁定和解锁 Surface 对象很多次，那么将锁定和解锁这对操作封装成独立的块也是很有用的（小甲鱼温馨提示：就像文件操作的打开和关闭）。
嵌套的锁定和解锁是安全的，Surface 对象会在最终的锁定被解除的时候解锁。

unlock()

功能：解锁 Surface 对象的内存使其无法进行像素访问。

属性：unlock() -> None

解锁已经锁定的 Surface 对象。解锁后的 Surface 对象才能再一次被绘制和被 Pygame 进行管理。
所有的 Pygame 函数在需要的时候都会自动锁定和解锁 Surface 对象。如果有部分代码需要反复锁定和解锁 Surface 对象很多次，那么将锁定和解锁这对操作封装成独立的块也是很有用的（小甲鱼温馨提示：就像文件操作的打开和关闭）。
嵌套的锁定和解锁是安全的，Surface 对象会在最终的锁定被解除的时候解锁。

mustlock()

功能：检测该 Surface 对象是否需要被锁定。

属性：mustlock() -> bool

如果返回 True，说明该 Surface 对象需要被锁定才能访问像素数据。通常，纯软件的 Surface 对象不需要锁定。为了快捷安全地确认需要锁定的所有 Surface 对象，该方法是必要的。
所有的 Pygame 函数在需要的时候都会自动锁定和解锁 Surface 对象。如果有部分代码需要反复锁定和解锁 Surface 对象很多次，那么将锁定和解锁这对操作封装成独立的块也是很有用的（小甲鱼温馨提示：就像文件操作的打开和关闭）。

get_locked()

功能：检测该 Surface 对象当前是否为锁定状态。

属性：get_locked() -> bool

当该 Surface 对象被锁定时（无论被重复锁定多少次），返回 True。

get_locks()

功能：返回该 Surface 对象的锁定。

属性：get_locks() -> tuple

返回该 Surface 对象当前存在的锁定。

get_at()

功能：获取一个像素的颜色值。
属性：get_at((x, y)) -> Color

返回指定像素点的 RGBA 颜色值。如果 Surface 对象的每个像素没有包含 alpha 通道，那么 alpha（A）的值将永远是 255（不透明）。如果指定像素的位置超出 Surface 对象的范围，将抛出 IndexError 异常。
在游戏或实时环境中，同时获取和设置多个像素会拖慢速度。更好的方法是使用一次性操作多个像素的方法，例如 blit()，fill() 和 draw() 方法，亦或者使用 surfarray / PixelArray 模块。
该函数会根据需求临时锁定和解锁 Surface 对象。

注意：Pygame 1.9.0 之前该函数是返回一个元祖，此后是返回一个 Color 对象。如果需要得到一个元祖，可以使用 tuple(surf.get_at((x,y))) 进行转换（一般只有在需要将颜色作为字典的键时，你才需要这么做）。

set_at()

功能：设置一个像素的颜色值。

属性：set_at((x, y), Color) -> None

设置指定像素点的颜色值，Color 参数可以使 RGBA 值，也可以是映射的颜色索引号。如果 Surface 对象的每个像素没有包含 alpha 通道，那么 alpha（A）的值将被忽略。如果指定像素的位置超出 Surface 对象的范围或剪切区域，那么该设置并不会生效。
在游戏或实时环境中，同时获取和设置多个像素会拖慢速度。
该函数会根据需求临时锁定和解锁 Surface 对象。

get_at_mapped()

功能：获取一个像素映射的颜色索引号。

属性：get_at_mapped((x, y)) -> Color

返回指定像素点映射的颜色索引号。如果指定像素的位置超出 Surface 对象的范围，将抛出 IndexError 异常。
该方法仅适用于 Pygame 的单元测试，不大适合在正式的应用程序中使用。
该函数会根据需求临时锁定和解锁 Surface 对象。

Pygame 1.9.2 新增加的。

get_palette()

功能：获取 Surface 对象 8 位索引的调色板。

属性：get_palette() -> [RGB, RGB, RGB, ...]

返回一个最多包含 Surface 对象映射的 256 种颜色的列表，事实上返回的列表就是调色板的拷贝，因此这个列表的修改并不会影响到 Surface 对象本身。

注意：Pygame 1.9.0 以后，返回值是一个包含 Color（长度为 3）对象的列表；在此之前，每个 RGB 元素是以元祖来表示的。

get_palette_at()

功能：返回给定索引号在调色板中的颜色值。

属性：get_palette_at(index) -> RGB

返回 index 参数在调色板中的颜色值，index 参数的取值范围是 0 ~ 255（8 位索引号）。

注意：Pygame 1.9.0 以后，返回值是一个包含 Color（长度为 3）对象；在此之前，是以元祖来表示 RGB 颜色值的。

set_palette()

功能：设置 Surface 对象 8 位索引的调色板。

属性：set_palette([RGB, RGB, RGB, ...]) -> None

设置 Surface 对象整个 8 位索引的调色板。该方法将会替换原有的调色板。
该函数将不会影响每个像素超过 8 位的 Surface 对象。

set_palette_at()

功能：设置给定索引号在调色板中的颜色值。

属性：set_palette_at(index, RGB) -> None

设置 index 参数在调色板中的颜色值，index 参数的取值范围是 0 ~ 255（8 位索引号）。
该函数将不会影响每个像素超过 8 位的 Surface 对象。

map_rgb()

功能：将一个 RGBA 颜色转换为映射的颜色值。

属性：map_rgb(Color) -> mapped_int

将一个 RGBA 颜色转换为该 Surface 对象映射的颜色值。返回值不会大于 Surface 对象的位深度。Pygame 常常不会使用这个映射的颜色值，但它可以用于传递给那些需要一个 Surface 对象以及其颜色的函数。

unmap_rgb()

功能：将一个映射的颜色值转换为 Color 对象。

属性：unmap_rgb(mapped_int) -> Color

将一个映射的颜色值转换为该 Surface 对象的 RGB 颜色。返回值不会大于 Surface 对象的位深度。Pygame 常常不会使用这个映射的颜色值，但它可以用于传递给那些需要一个 Surface 对象以及其颜色的函数。

set_clip()

功能：设置该 Surface 对象的当前剪切区域。

属性：

set_clip(rect) -> None
set_clip(None) -> None

每个 Surface 对象拥有一个活跃的剪切区域。剪切区域是指 Surface 对象上的一个限定矩形，只有该矩形内的像素才可以被修改。如果传入 None，表示剪切区域覆盖整个 Surface 对象。
剪切区域受限于 Surface 对象本身。如果剪切区域过大，那么将被缩小到匹配 Surface 对象的范围。

get_clip()

功能：获取该 Surface 对象的当前剪切区域。

属性：get_clip() -> Rect

返回该 Surface 对象的当前剪切区域，用一个 Rect 对象来描述。Surface 对象返回的限定矩形永远不会超出图像的边界。
如果该 Surface 对象没有设置剪切区域，那么将返回整个图像那么大的限定矩形。

subsurface()

功能：根据父对象创建一个新的子 Surface 对象。

属性：subsurface(Rect) -> Surface

返回一个子 Surface 对象，它将与父对象共享所有的像素。修改子对象或父对象任一的像素均会影响到彼此，Surface 对象的信息像剪切区域，color keys 都是相同的。
新的子对象将从它的父对象中继承调色板、color keys 和 alpha 通道的设置。
存在多个子 Surface 对象以及子子 Surface 对象（subsubsurface）均是可以的。在显示模式不是硬件加速状态时，也是支持子 Surface 对象的。

更多有关子 Surface 对象的内容请查看：get_offset() 和 get_parent() 方法。

get_parent()

功能：获取子 Surface 对象的父对象。

属性：get_parent() -> Surface

返回子 Surface 对象的父对象，如果不存在父对象，则返回 None。

get_abs_parent()

功能：获取子 Surface 对象的顶层父对象。

属性：get_abs_parent() -> Surface

返回子 Surface 对象的父对象，如果不存在父对象，则返回该 Surface 对象本身（如果没有父对象，本身及顶层父对象）。

get_offset()

功能：获取子 Surface 对象在父对象中的偏移位置。

属性：get_offset() -> (x, y)

获取子 Surface 对象在父对象中的偏移位置。如果该 Surface 对象不是子对象，则返回 (0, 0)。

get_abs_offset()

功能：获取子 Surface 对象在顶层父对象中的偏移位置。

属性：get_abs_offset() -> (x, y)

获取子 Surface 对象在顶层父对象中的偏移位置。如果该 Surface 对象不是子对象，则返回 (0, 0)。

get_size()

功能：获取 Surface 对象的尺寸。

属性：get_size() -> (width, height)

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

get_width()

功能：获取 Surface 对象的宽度。

属性：get_width() -> width

返回 Surface 对象的宽度，以像素为单位。

get_height()

功能：获取 Surface 对象的宽度。

属性：get_height() -> height

返回 Surface 对象的高度，以像素为单位。

get_rect()

功能：获取 Surface 对象的矩形区域。

属性：get_rect(**kwargs) -> Rect

返回一个 Rect 对象表示该 Surface 对象的矩形区域。该矩形对象（Rect）总是以 (0, 0) 为起点，width 和 height 为图像的尺寸。可以给该函数传递关键字参数【例如：image.get_rect(center=(20, 20))】，返回的结果将受参数的影响。

get_bitsize()

功能：获取 Surface 对象像素格式的位深度。

属性：get_bitsize() -> int

返回该 Surface 对象中每个像素用多少位来表示。该值可能不会完全与每个像素所使用的字节数相同。例如一个 15 位深度的 Surface 对象依然需要 2 个字节来存放。

get_bytesize()

功能：获取 Surface 对象每个像素使用的字节数。

属性：get_bytesize() -> int

返回 Surface 对象每个像素使用的字节数。

get_flags()

功能：获取 Surface 对象的附加标志。

属性：get_flags() -> int

返回当前 Surface 对象的特征。每个特征都是一个位掩码标志。典型标志有 HWSURFACE，RLEACCEL，SRCALPHA 和 SRCCOLORKEY。

下边是一个相对比较全面的标志列表，全部标志可在 SDL_video.h 文件中找到。

SWSURFACE	0x00000000	将创建出来的 Surface 对象存放于内存中
HWSURFACE	0x00000001	将创建出来的 Surface 对象存放于显存中
ASYNCBLIT	0x00000004	使用异步绘制（如果可能的话）

以下标志 display 模块的 set_mode() 方法适用：

ANYFORMAT	0x10000000	显存中可以是深度格式或者是像素格式
HWPALETTE	0x20000000	该 Surface 对象独占一个调色板
DOUBLEBUF	0x40000000	双缓冲模式
FULLSCREEN	0x80000000	全屏显示
OPENGL	0x00000002	创建一个 OpenGL 渲染的环境
OPENGLBLIT	0x0000000A	创建一个 OpenGL 渲染的环境并用于绘制（过时）
RESIZABLE	0x00000010	允许调整尺寸
NOFRAME	0x00000020	不显示窗口标题栏和边框

内部使用（只读）：

HWACCEL	0x00000100	使用硬件加速绘制
SRCCOLORKEY	0x00001000	使用源 color key 绘制
RLEACCELOK	0x00002000	私有标志
RLEACCEL	0x00004000	使用 RLE 编码 Surface 对象
SRCALPHA	0x00010000	使用源 alpha 混合绘制
PREALLOC	0x01000000	使用预分配内存

get_pitch()

功能：获取 Surface 对象每行占用的字节数。

属性：get_pitch() -> int

返回该 Surface 对象每行占用的字节数，存放在显存中的 Surface 对象并不总是线性填充。子 Surface 对象会比实际拥有更大的间距。

该方法不适用于通常的 Pygame 开发。

get_masks()

功能：获取用于颜色与映射索引号之间转换的掩码。

属性：get_masks() -> (R, G, B, A)

返回一个掩码，用于在颜色和映射索引号之间进行转换。

set_masks()

功能：设置用于颜色与映射索引号之间转换的掩码。

属性：set_masks((r,g,b,a)) -> None

Pygame 1.8.1 新增加的，该方法不适用于通常的 Pygame 开发。

get_shifts()

功能：获取当位移动时在颜色与映射索引号之间转换的掩码。

属性：get_shifts() -> (R, G, B, A)

返回当像素移动时在颜色与映射索引号之间转换的掩码。

该方法不适用于通常的 Pygame 开发。

set_shifts()

功能：设置当位移动时在颜色与映射索引号之间转换的掩码。

属性：set_shifts((r,g,b,a)) -> None

Pygame 1.8.1 新增加的，该方法不适用于通常的 Pygame 开发。

get_losses()

功能：获取最低有效位在颜色与映射索引号之间转换的掩码。

属性：get_losses() -> (R, G, B, A)

返回最低有效位在颜色与映射索引号之间转换的掩码。

该方法不适用于通常的 Pygame 开发。

get_bounding_rect()

功能：获取最小包含所有数据的 Rect 对象。

属性：get_bounding_rect(min_alpha = 1) -> Rect

返回一个包含整个 Surface 对象所有的像素并且 alpha 值大于等于平均 alpha 值的最小矩形区域。

Pygame 1.8.1 新增加的。

get_view()

功能：获取 Surface 对象的像素缓冲区视图。

属性：get_view(<kind>=‘2’) -> BufferProxy

返回一个 BufferProxy 对象，它用 C 级别的数组结构输出 Surface 对象内部的像素缓冲区，Python 级别的数组或 C 级别的缓冲区作为接口。输出的像素缓冲区是可写的。新的缓冲区协议支持 Python 2.6 以上和 CPython。旧的缓冲区协议也支持 Python 2.x。旧的缓冲区数据是由一个 <kind>='0' 及多个其他缓冲区视图构成。

kind 参数是一个字节的字符串：'0'，'1'，'2'，'3'，'r'，'g'，'b' 或 'a'。字母不区分大小写，因此 'A' 也是可以的。参数可以是 Unicode 或 byte 字符串。默认值是 '2'。

'0'	返回一个连续的非结构化字节的视图。	没有给出 Surface 对象形状的信息。如果 Surface 对象的像素是不连续的，将抛出 ValueError 异常。
'1'	返回一个连续像素的数组（宽 * 高）。	如果 Surface 对象的像素是不连续的，将抛出 ValueError 异常。
'2'	返回一个原始像素的数组（宽，高）。	Surface 对象的像素是字节尺寸的无符号整数。像素格式是由 Surface 对象指定。与其他的 Pygame 函数大相庭径，24 位的 Surface 对象用 3 个无符号整数表示。
'3'	返回一个由 RGB 组成的数组（宽，高，3）。	红、绿、蓝每个组成颜色均是一个无符号字节。只有 24 位和 32 位的 Surface 对象支持。像素的颜色组合必须是 RGB 或 BGR 顺序。
'r' 表示红色 'g' 表示绿色 'b' 表示蓝色 'a' 表示 alpha 通道。	返回 Surface 对象的单一颜色视图（宽，高）。	只有 24 位和 32 位的 Surface 对象支持 'r'，'g' 和 'b'，只有带有 SRCALPHA 标志的 Surface 对象支持 'a'。

只有当输出接口被访问时，该 Surface 对象是锁定的。对于访问新的缓冲区接口，一旦最后的缓冲区视图被释放，该 Surface 对象即解锁。对于访问数组接口和旧的缓冲区接口，该 Surface 对象保持锁定直到 BufferProxy 对象被释放。

Pygame 1.9.2 新增加的。

get_buffer()

功能：获取 Surface 对象的像素缓冲区对象。

属性：get_buffer() -> BufferProxy

返回一个 BufferProxy 的缓冲区对象，用于表示 Surface 对象的像素。该缓冲区对象可以被直接访问和操作。Surface 对象的像素数据被表示为非结构化的块保存，拥有一个开始地址和长度描述。数据不需要连续，任何间隔均会被计算入长度中，但在其他方面中忽略。
该方法隐式地锁定 Surface 对象。当 BufferProxy 对象被释放时将会解锁。

Pygame 1.8 新增加的。