pygame之Surface模块

                          Surface-用于表示图像的Pygame对象

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

Surface((width, height), flags=0, Surface) -> Surface

pygame.Surface.blit—将一个图像绘制到另一个

pygame.Surface.blits—将许多图像绘制到另一个

pygame.Surface.convert—更改图像的像素格式

pygame.Surface.convert_alpha—改变包括每像素α的图像的像素格式

pygame.Surface.copy—创建Surface的新副本

pygame.Surface.fill—用纯色填充Surface

pygame.Surface.scroll—将表面图像移动到位

pygame.Surface.set_colorkey—设置透明颜色键

pygame.Surface.get_colorkey—获取当前透明的colorkey

pygame.Surface.set_alpha—设置完整Surface图像的Alpha值

pygame.Surface.get_alpha—获取当前的Surface透明度值

pygame.Surface.lock—锁定Surface内存以进行像素访问

pygame.Surface.unlock—从像素访问中解锁Surface存储器

pygame.Surface.mustlock—测试Surface是否需要锁定

pygame.Surface.get_locked—测试Surface是否被当前锁定

pygame.Surface.get_locks—获取Surface的锁

pygame.Surface.get_at—获取单个像素的颜色值

pygame.Surface.set_at—设置单个像素的颜色值

pygame.Surface.get_at_mapped—获取单个像素的映射颜色值

pygame.Surface.get_palette—获取8位Surface的颜色索引调色板

pygame.Surface.get_palette_at—获取调色板中单个条目的颜色

pygame.Surface.set_palette—设置8位Surface的调色板

pygame.Surface.set_palette_at—在8位Surface调色板中设置单个索引的颜色

pygame.Surface.map_rgb—将颜色转换为映射的颜色值

pygame.Surface.unmap_rgb—将映射的整数颜色值转换为颜色

pygame.Surface.set_clip—设置Surface的当前剪切区域

pygame.Surface.get_clip—获取Surface的当前剪切区域

pygame.Surface.subsurface—创建一个引用其父级的新表面

pygame.Surface.get_parent—找到地下的父母

pygame.Surface.get_abs_parent—找到地下的顶级父级

pygame.Surface.get_offset—在父母中找到子地下的位置

pygame.Surface.get_abs_offset—在其顶级父级中查找子级子表面的绝对位置

pygame.Surface.get_size—获取Surface的尺寸

pygame.Surface.get_width—获取Surface的宽度

pygame.Surface.get_height—获得Surface的高度

pygame.Surface.get_rect—得到Surface的矩形区域

pygame.Surface.get_bitsize—获取Surface像素格式的位深度

pygame.Surface.get_bytesize —获取每个Surface像素使用的字节数

pygame.Surface.get_flags—获取用于Surface的其他标志

pygame.Surface.get_pitch— 获取每个Surface行使用的字节数

pygame.Surface.get_masks—位掩码需要在颜色和映射的整数之间进行转换

pygame.Surface.set_masks—设置在颜色和映射整数之间转换所需的位掩码

pygame.Surface.get_shifts—在颜色和映射的整数之间转换所需的位移

pygame.Surface.set_shifts—设置在颜色和映射整数之间转换所需的位移

pygame.Surface.get_losses—用于在颜色和映射整数之间进行转换的有效位

pygame.Surface.get_bounding_rect—找到包含数据的最小rect

pygame.Surface.get_view—返回Surface像素的缓冲区视图。

pygame.Surface.get_buffer—获取Surface的像素的缓冲对象。

pygame.Surface._pixels_address—像素缓冲地址

pygame Surface用于表示任何图像。Surface具有固定的分辨率和像素格式。具有8位像素的表面使用调色板映射到24位颜色。调用pygame.Surface()以创建新的图像对象。Surface将被清除为全黑。唯一需要的参数是尺寸。如果没有其他参数，Surface将以与显示Surface最匹配的格式创建。可以通过传递位深度或现有Surface来控制像素格式。flags参数是表面附加功能的位掩码。您可以传递这些标志的任意组合：

HWSURFACE, creates the image in video memory

SRCALPHA, the pixel format will include a per-pixel alpha

这两个标志只是一个请求，可能不适用于所有显示和格式。高级用户可以将一组位掩码与深度值组合在一起。掩码是一组4个整数，表示像素中的哪些位代表每种颜色。Normal Surfaces不应该需要mask参数。曲面可以有许多额外的属性，如alpha平面，颜色键，源矩形剪裁。这些函数主要影响Surface如何与其他Surface进行blit。blit例程将尽可能尝试使用硬件加速，否则他们将使用高度优化的软件blitting方法。pygame支持三种类型的透明度：colorkeys，surface alphas和pixel alphas。表面alphas可以与colorkeys混合使用，但是每像素alphas的图像不能使用其他模式。Colorkey透明度使单个颜色值透明。不会绘制与colorkey匹配的任何像素。曲面alpha值是单个值，用于更改整个图像的透明度。表面alpha为255是不透明的，值为0是完全透明的。每个像素的alpha值不同，因为它们为每个像素存储透明度值。这允许最精确的透明效果，但它也是最慢的。每像素alphas不能与表面alpha和colorkeys混合使用。

支持Surfaces的像素访问。硬件表面上的像素访问速度很慢，不推荐使用。可以使用get_at()和set_at()函数访问像素 。这些方法适用于简单访问，但在使用它们进行像素处理时会相当慢。如果您计划进行大量的像素级工作，建议使用 pygame.PixelArraypygame对象进行曲面的直接像素访问，这样就可以得到类似于曲面视图的数组。对于所涉及的数学操作，尝试pygame.surfarray使用阵列接口 模块访问表面像素数据的pygame模块(它非常快，但需要NumPy。)

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

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

曲面还可以引用其他曲面的部分。这些是使用该Surface.subsurface()方法创建的。对Surface的任何更改都会影响另一个。

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

blit() 将一个图像绘制到另一个

blit(source，dest，area = None，special_flags = 0) - > Rect

在此Surface上绘制源Surface。可以使用dest参数定位绘图。Dest可以是表示源左上角的坐标对。Rect也可以作为目标传递，矩形的topleft角将用作blit的位置。目标矩形的大小不会影响blit。也可以传递可选的区域矩形。返回矩形是受影响像素的区域，不包括目标Surface外部或剪切区域外的任何像素。当blitting到8位Surface时，将忽略像素alpha。pygame 1.8中的special_flags新增功能。

blits() 将许多图像绘制到另一个

blits(blit_sequence =(source，dest)，...)，doreturn = 1) - >(Rect，...)

blits((source，dest，area)，...)) - >(Rect，...)

blits((source，dest，area，special_flags)，...)) - >(Rect，...)

在此Surface上绘制许多曲面。它需要一个序列作为输入，每个元素对应于Surface.blit()。它至少需要一个(source，dest)序列。参数：   

blit_sequence - 一系列曲面，以及blit它们的参数。它们对应于Surface.blit()参数。

doreturn - 如果为true，我们返回否则返回None。

返回：   

更改区域的列表。如果doreturn为false，则返回None。

convert() 更改图像的像素格式

convert(Surface) -> Surface

convert(depth, flags=0) -> Surface

convert(masks, flags=0) -> Surface

convert() -> Surface

使用更改的像素格式创建Surface的新副本。可以从另一个现有Surface确定新的像素格式。否则，可以使用depth，flags和mask参数，类似于 pygame.Surface()调用。如果没有传递参数，则新Surface将具有与显示Surface相同的像素格式。这总是最快的blitting格式。在将所有Surface多次blit之前转换它们是一个好主意。转换后的Surface将没有像素alpha。如果原件有它们，它们将被剥离。请参阅Surface.convert_alpha()保留或创建每像素alpha。新副本将与复制的表面具有相同的类。这使得Surface子类继承此方法而无需覆盖，除非子类特定的实例属性也需要复制。

convert_alpha() 改变包括每像素α的图像的像素格式

convert_alpha(Surface) - > Surface

convert_alpha() - > Surface

使用所需的像素格式创建曲面的新副本。新表面将采用适合快速blitting到给定格式的格式，每像素alpha。如果没有给出表面，则新表面将针对当前显示的blitting进行优化。与该Surface.convert()方法不同，新图像的像素格式与请求的源不完全相同，但它将针对到目的地的快速alpha blitting进行优化。与Surface.convert()返回的曲面具有与转换曲面相同的类。

copy() 创建Surface的新副本

copy() - > Surface

制作Surface的副本。新曲面将具有与原始曲面相同的像素格式，调色板，透明度设置和类。如果Surface子类还需要复制任何特定于实例的属性，那么它应该覆盖copy()。

fill() 用纯色填充Surface

fill(color，rect = None，special_flags = 0) - > Rect

用纯色填充表面。如果没有给出rect参数，则将填充整个Surface。rect参数将填充限制为特定区域。填充也将包含在Surface剪辑区域中。color参数可以是RGB序列，RGBA序列或映射的颜色索引。如果使用RGBA，RGBA则忽略Alpha(A的一部分 )，除非表面使用每像素alpha(Surface具有SRCALPHA标记)。这将返回受影响的Surface区域。

scroll() 将表面图像移动到位

scroll(dx=0, dy=0) -> None

将图像向右移动dx像素，向下移动dy像素。对于左侧和上侧滚动，dx和dy可能分别为负。未被覆盖的表面区域保留其原始像素值。滚动包含在Surface剪辑区域中。使dx和dy值超过表面大小是安全的。

set_colorkey() 设置透明颜色键

set_colorkey(Color，flags = 0) - >无

set_colorkey(无) - >无

设置Surface的当前颜色键。将此Surface blitting到目标上时，与colorkey颜色相同的任何像素都将是透明的。颜色可以是RGB颜色或映射的颜色整数。如果未传递，则将取消设置颜色键。如果将Surface格式化为使用每像素alpha值，则将忽略colorkey。colorkey可以与完整的Surface alpha值混合使用。可以将可选的flags参数设置为pygame.RLEACCEL在非加速显示上提供更好的性能。的RLEACCEL表面会更慢进行修改，但更快的blit作为源。

get_colorkey() 获取当前透明的colorkey

get_colorkey() - > RGB或None

返回Surface的当前colorkey值。如果未设置colorkey，则返回None。

set_alpha() 设置完整Surface图像的Alpha值

set_alpha(value, flags=0) -> None

set_alpha(None) -> None

设置Surface的当前alpha值。将此Surface渲染到目标上时，像素将被绘制为略微透明。alpha值是0到255之间的整数，0表示完全透明，255表示完全不透明。如果为Alpha值传递None，则将禁用Surface alpha。此值与每像素Surface alpha不同。对于具有每像素alpha的曲面，将忽略覆盖alpha并None返回。可以将可选的flags参数设置为pygame.RLEACCEL在非加速显示上提供更好的性能。的RLEACCEL表面会更慢进行修改，但更快的blit作为源。

get_alpha() 获取当前的Surface透明度值

get_alpha() - > int_value

返回Surface的当前Alpha值。

lock() 锁定Surface内存以进行像素访问

lock() - >None

锁定Surface的像素数据以进行访问。在加速表面上，像素数据可以存储在易失性视频存储器或非线性压缩形式中。当Surface锁定时，像素存储器可供常规软件访问。读取或写入像素值的代码需要锁定Surface。表面不应保持锁定超过必要的程度。通常不能通过pygame显示或管理锁定的Surface。并非所有Surfaces都需要锁定。该Surface.mustlock()方法可以确定它是否实际需要。锁定和解锁不需要它的Surface没有性能损失。所有pygame函数都会根据需要自动锁定和解锁Surface数据。如果一段代码要进行多次重复锁定和解锁Surface的调用，将块包装在锁定和解锁对中会很有帮助。嵌套锁定和解锁呼叫是安全的。只有在释放最终锁定后才能解锁表面。

unlock() 从像素访问中解锁Surface存储器

unlock() - >无

锁定后解锁Surface像素数据。解锁的Surface可以再次由pygame绘制和管理。有关Surface.lock()详细信息，请参阅文档。所有pygame函数都会根据需要自动锁定和解锁Surface数据。如果一段代码要进行多次重复锁定和解锁Surface的调用，将块包装在锁定和解锁对中会很有帮助。嵌套锁定和解锁呼叫是安全的。只有在释放最终锁定后才能解锁表面。

mustlock() 测试Surface是否需要锁定

mustlock() - > bool

如果需要锁定Surface以访问像素数据，则返回True。通常纯软件Surfaces不需要锁定。很少需要这种方法，因为根据需要锁定所有Surface是安全且最快的。所有pygame函数都会根据需要自动锁定和解锁Surface数据。如果一段代码要进行多次重复锁定和解锁Surface的调用，将块包装在锁定和解锁对中会很有帮助。

get_locked() 测试Surface是否被当前锁定

get_locked() - > bool

Surface锁定时返回True。Surface被锁定的次数无关紧要。

get_locks() 获取Surface的锁

get_locks() - >元组

返回Surface的当前现有锁。

get_at() 获取单个像素的颜色值

get_at((x，y)) - >颜色

返回RGBA给定像素的Color值的副本。如果Surface没有每像素alpha，那么alpha值将始终为255(不透明)。如果像素位置在Surface区域之外，则会引发IndexError异常。一次获取和设置一个像素通常太慢，无法在游戏或实时情况下使用。最好使用一次操作多个像素的方法，比如blit，fill和draw方法 - 或者使用surfarray / PixelArray。此功能将根据需要临时锁定和解锁Surface。返回颜色而不是元组，在pygame 1.9.0中新增。使用 tuple(surf.get_at((x,y)))，如果你想有一个元组，而不是颜色。这应该只在您想要将颜色用作字典中的键时才有意义。

set_at() 设置单个像素的颜色值

set_at((x，y)，Color) - >无

RGBA为单个像素设置或映射整数颜色值。如果Surface没有每像素alphas，则忽略alpha值。在“曲面”区域外部或“曲面”剪裁外部设置像素将不起作用。一次获取和设置一个像素通常太慢，无法在游戏或实时情况下使用。此功能将根据需要临时锁定和解锁Surface。

get_at_mapped() 获取单个像素的映射颜色值

get_at_mapped((x, y)) -> Color

返回给定像素的整数值。如果像素位置在Surface区域之外，则会引发IndexError异常。此方法适用于pygame单元测试。它不太可能在应用程序中使用。此功能将根据需要临时锁定和解锁Surface。

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

get_palette() - > [RGB，RGB，RGB，...]

返回最多256个颜色元素的列表，这些颜色元素表示8位Surface中使用的索引颜色。返回的列表是调色板的副本，更改将对Surface无效。在pygame 1.9.0中返回实例列表而不是元组，NewColor(with length 3)

get_palette_at() 获取调色板中单个条目的颜色

get_palette_at(index) - > RGB

返回“曲面”调板中单个索引的红色，绿色和蓝色值。索引应该是0到255之间的值。在pygame 1.9.0中返回实例而不是元组，NewColor(with length 3)

set_palette() 设置8位Surface的调色板

set_palette([RGB，RGB，RGB，...]) - >无

设置8位Surface的完整调色板。这将替换现有调色板中的颜色。可以传递部分调色板，仅更改原始调色板中的第一种颜色。

此功能对每像素超过8位的Surface没有影响。

set_palette_at() 在8位Surface调色板中设置单个索引的颜色

set_palette_at(index，RGB) - >无

在“曲面”调板中为单个条目设置调色板值。索引应该是0到255之间的值。此功能对每像素超过8位的Surface没有影响。

map_rgb() 将颜色转换为映射的颜色值

map_rgb(Color) - > mapped_int

将RGBA颜色转换为此Surface的映射整数值。返回的整数将不包含比Surface的位深度更多的位。映射的颜色值通常不在pygame中使用，但可以传递给大多数需要Surface和颜色的函数。有关颜色和像素格式的详细信息，请参阅Surface对象文档。

unmap_rgb() 将映射的整数颜色值转换为颜色

unmap_rgb(mapped_int) - >颜色

将映射的整数颜色转换RGB为此Surface 的颜色分量。映射的颜色值通常不在pygame中使用，但可以传递给大多数需要Surface和颜色的函数。有关颜色和像素格式的详细信息，请参阅Surface对象文档。

set_clip() 设置Surface的当前剪切区域

set_clip(rect) -> None

set_clip(None) -> None

每个Surface都有一个活动的剪切区域。这是一个矩形，表示Surface上可以修改的唯一像素。如果为矩形传递无，则完整的Surface将可用于更改。剪切区域始终限制在Surface本身的区域。如果剪辑矩形太大，它将缩小以适合Surface内部。

get_clip() 获取Surface的当前剪切区域

get_clip() - > Rect

返回当前剪切区域的矩形。Surface将始终返回一个永远不会超出图像边界的有效矩形。如果Surface为剪切区域设置了None，则Surface将返回一个带有Surface整个区域的矩形。

subsurface() 创建一个引用其父级的新表面

subsurface(Rect) - > Surface

返回一个与其新父级共享像素的新Surface。新的Surface被认为是原始的孩子。对Surface像素的修改将相互影响。剪切区域和颜色键等曲面信息对于每个曲面都是唯一的。新的Surface将从其父级继承调色板，请参阅Surface.get_offset()，Surface.get_parent()原文以了解有关子级状态的更多信息。

get_parent() 找到父级Surface

get_parent() - > Surface

返回父级Surface。如果这不是父级Surface，那么将返回None。

get_abs_parent() 找到顶级父级Surface

get_abs_parent() - > Surface

返回顶级父级Surface。如果这不是顶级父级Surface，那么将返回此Surface。

get_offset() 在父级中找到子级的位置

get_offset() - >(x，y)

获取父项内子项下的偏移位置。如果Surface不是子级，则返回(0,0)。

get_abs_offset() 在其顶级父级中查找子级Surface的绝对位置

get_abs_offset() - >(x，y)

获取子级子表面在其顶级父级Surface内的偏移位置。如果Surface不是子级，则返回(0,0)。

get_size() 获取Surface的尺寸

get_size() - >(宽度，高度)

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

get_width() 获取Surface的宽度

get_width() - > width

返回Surface的宽度(以像素为单位)。

get_height() 获得Surface的高度

get_height() - >高度

返回Surface的高度(以像素为单位)。

get_rect() 得到Surface的矩形区域

get_rect(** kwargs) - > Rect

返回覆盖整个曲面的新矩形。此矩形始终从0开始，宽度为0。和高度与图像大小相同。您可以将关键字参数值传递给此函数。这些命名值将在返回之前应用于Rect的属性。一个例子是'mysurf.get_rect(center =(100,100))'来创建一个以给定位置为中心的Surface矩形。

get_bitsize() 获取Surface像素格式的位深度

get_bitsize() - > int

返回用于表示每个像素的位数。此值可能无法准确填充每个像素使用的字节数。例如，15位Surface仍需要完整的2个字节。

get_bytesize() 获取每个Surface像素使用的字节数

get_bytesize() - > int

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

get_flags() 获取用于Surface的其他标志

get_flags() - > int

返回一组当前Surface要素。每个功能都在标志位掩码中。典型的标志是HWSURFACE，RLEACCEL， SRCALPHA，和SRCCOLORKEY。这是一个更完整的标志列表。参数详见原文。

get_pitch() 获取每个Surface行使用的字节数

get_pitch() - > int

返回分隔Surface中每行的字节数。视频内存中的表面并不总是线性打包。次表面也将具有比其实际宽度更大的间距。正常的pygame使用不需要此值。

get_masks() 位掩码需要在颜色和映射的整数之间进行转换

get_masks() - >(R，G，B，A)

返回用于隔离映射整数中每种颜色的位掩码。正常的pygame使用不需要此值。

set_masks() 设置在颜色和映射整数之间转换所需的位掩码

set_masks((r，g，b，a)) - >无

正常的pygame使用不需要这个。pygame 1.8.1中的新功能

get_shifts() 在颜色和映射的整数之间转换所需的位移

get_shifts() - >(R，G，B，A)

返回在每种颜色和映射的整数之间转换所需的像素移位。正常的pygame使用不需要此值。

set_shifts() 设置在颜色和映射整数之间转换所需的位移

set_shifts((r，g，b，a)) - >无

正常的pygame使用不需要这个。pygame 1.8.1中的新功能

get_losses() 用于在颜色和映射整数之间进行转换的有效位

get_losses() - >(R，G，B，A)

返回从映射整数中的每种颜色剥离的最低有效位数。正常的pygame使用不需要此值。

get_bounding_rect() 找到包含数据的最小rect

get_bounding_rect(min_alpha = 1) - > Rect

返回包含曲面中具有大于或等于最小alpha值的alpha值的所有像素的最小矩形区域。此功能将根据需要临时锁定和解锁Surface。

get_view() 返回Surface像素的缓冲区视图。

get_view(<kind> ='2') - > BufferProxy

返回一个对象，该对象将表面的内部像素缓冲区导出为C级数组结构，Python级别数组接口或C级缓冲区接口。像素缓冲区是可写的。在Python 2.6及更高版本的CPython中支持新的缓冲区协议。Python 2.x也支持旧的缓冲区协议。旧缓冲区数据在一个段中用于类型'0'，多段用于其他缓冲区视图类型。类型参数是长度为1的字符串'0'，'1'，'2'，'3'，'r'，'g'，'b'或'a'。这些字母不区分大小写; 'A'也会起作用。参数可以是Unicode或字节(char)字符串。默认值为“2”。

'0'返回连续的非结构化字节视图。没有给出表面形状信息。如果曲面的像素不连续，则会引发ValueError。

'1'返回连续像素的(表面宽度*表面高度)数组。如果表面像素不连续，则会引发ValueError。

'2'返回原始像素的(表面宽度，表面高度)数组。像素是surface-bytesize-d无符号整数。像素格式是表面特定的。除了其他pygame函数之外，其他任何东西都不太可能接受24位表面的3字节无符号整数。

'3'返回(表面宽度，表面高度，3)RGB颜色分量数组。红色，绿色和蓝色组件中的每一个都是无符号字节。仅支持24位和32位曲面。颜色分量必须在像素内RGB或BGR在像素内。

红色为'r'，绿色为'g'，蓝色为'b'，alpha为'a'，返回表面内单个颜色分量的(表面宽度，表面高度)视图：颜色平面。颜色分量是无符号字节。24位和32位表面都支持'r'，'g'和'b'。只SRCALPHA支持'a'的32位曲面 。

只有在访问公开的接口时才会锁定表面。对于新的缓冲区接口访问，一旦释放最后一个缓冲区视图，就会解锁表面。对于阵列接口和旧缓冲区接口访问，表面将保持锁定状态，直到释放BufferProxy对象。

get_buffer() 获取Surface的像素的缓冲对象。

get_buffer() - > BufferProxy

返回Surface的像素的缓冲区对象。缓冲区可用于直接像素访问和操作。表面像素数据表示为非结构化的内存块，其起始地址和长度以字节为单位。数据不必是连续的。任何间隙都包含在长度中，但否则会被忽略。此方法隐式锁定Surface。当返回的BufferProxy对象被垃圾回收时，将释放锁。

_pixels_address 像素缓冲地址

_pixels_address - > int

曲面的原始像素字节的起始地址。