表面

类表面（）

class cairo.Surface

surface是抽象类型，表示cairo可以呈现给的所有不同绘图目标。实际图纸使用 Context .

cairo.surface是通过使用cairo.<xxx>surface（）形式的后端特定构造函数创建的。

表面 是从中派生所有其他曲面类的抽象基类。它不能直接实例化。

备注

在 1.17.0 版本加入: cairo.Surface 可以用作上下文管理器：

# surface.finish() will be called on __exit__
with cairo.SVGSurface("example.svg", 200, 200) as surface:
    pass

# surface.unmap_image(image_surface) will be called on __exit__
with surface.map_to_image(None) as image_surface:
    pass

__init__()

copy_page() → None

为支持多页但不清除的后端发出当前页，以便将当前页的内容保留到下一页。使用 show_page() 如果你想在发射后得到一个空白页。

Context.copy_page() 是一个方便的函数。

在 1.6 版本加入.

create_for_rectangle(x: float, y: float, width: float, height: float) → Surface

参数:

• x -- 目标表面左上角的子表面X原点（以设备空间单位表示）

• y -- 目标表面左上角的子表面的Y原点（以设备空间单位表示）

• width -- 子表面的宽度（以设备空间单位表示）

• height -- 子表面高度（以设备空间单位表示）

返回:

新的表面

在目标曲面中创建一个矩形的新曲面。所有绘制到此曲面的操作都将被剪裁并转换到目标曲面上。通过此子曲面在其边界之外绘制的任何内容都不会绘制到目标曲面上，因此这是将受约束的子曲面传递给直接绘制到父曲面上的库例程的一种有用方法，即不需要进一步的后端分配、双缓冲或副本。

备注

子表面的语义还没有最终确定，除非矩形是完整的设备单元，包含在目标表面的范围内，并且目标或子表面的设备转换没有更改。

在 1.12.0 版本加入.

create_similar(content: Content, width: int, height: int) → Surface

参数:

• content -- 新表面的内容

• width -- 新表面的宽度（以设备空间单位表示）

• height -- 新表面的高度（以设备空间单位表示）

返回:

新分配的 表面 .

创建一个 表面 与现有表面尽可能兼容。例如，新曲面将具有相同的回退分辨率和 FontOptions . 通常，新的表面也将使用相同的后端，除非这是出于某种原因不可能的。

最初，表面内容全部为0（如果内容具有透明度，则为透明，否则为黑色）。

create_similar_image(format: Format, width: int, height: int) → ImageSurface

参数:

• format (cairo.Format) -- 新曲面的格式

• width -- 新表面的宽度（以设备空间单位表示）

• height -- 新表面的高度（以设备空间单位表示）

返回:

新的图像表面

创建尽可能兼容的新图像曲面，以便上载到现有曲面并与现有曲面一起使用。然而，这个表面仍然可以像任何正常的图像表面一样使用。

最初，表面内容全部为0（如果内容具有透明度，则为透明，否则为黑色）。

在 1.12.0 版本加入.

finish() → None

此方法完成Surface并删除对外部资源的所有引用。例如，对于Xlib后端，这意味着cairo将不再访问可以释放的可抽屉。在调用Finish()之后，Surface上唯一有效的操作是刷新和完成它。进一步绘制到曲面不会影响曲面，而是会触发 cairo.Error 例外。

flush() → None

为…做任何挂起的绘图 表面 同时恢复开罗对 表面的 州。在从绘图切换到 表面 使用cairo可以直接使用本地API进行绘制。如果 表面 不支持直接访问，则此函数不起任何作用。

get_content() → Content

返回:

的内容类型 表面 ，表示 表面 包含颜色和/或字母信息。

在 1.2 版本加入.

get_device() → Device | None

返回:

设备或 None 如果表面没有关联的设备

此函数返回曲面的设备。

在 1.14.0 版本加入.

get_device_offset() → Tuple[float, float]

返回:

（X轴偏移，Y轴偏移）浮点元组 * x_offset: the offset in the X direction, in device units * Y轴偏移：Y轴方向的偏移量，单位为设备单位。

此方法返回由设置的上一个设备偏移量 set_device_offset() .

在 1.2 版本加入.

get_device_scale() → Tuple[float, float]

返回:

（x诳scale，y诳scale）浮点数的2元组

此函数返回由设置的上一个设备偏移量 Surface.set_device_scale() .

在 1.14.0 版本加入.

get_fallback_resolution() → Tuple[float, float]

返回:

（x像素/英寸，y像素/英寸）一组浮点 * x_pixels_per_inch: horizontal pixels per inch * Y像素/英寸：垂直像素/英寸

此方法返回由 set_fallback_resolution() 或默认回退解决方案（如果从未设置）。

在 1.8 版本加入.

get_font_options() → FontOptions

返回:

一 FontOptions

检索的默认字体呈现选项 表面 . 这允许显示曲面报告在其上呈现的正确子像素顺序，打印曲面以禁用指标提示等。结果可用于 ScaledFont .

get_mime_data(mime_type: str) → bytes | None

参数:

mime_type -- 图像数据的mime类型 (cairo.MIME_TYPE ）

返回:

bytes or None

返回以前附加到曲面的mime数据 set_mime_data() 使用指定的mime类型。如果给定的mime类型没有附加任何数据， None 返回。

在 1.12.0 版本加入.

has_show_text_glyphs() → bool

返回:

True 如果表面支撑 Context.show_text_glyphs() ， False 否则

返回曲面是否支持复杂 Context.show_text_glyphs() 操作。也就是说，它是否实际使用提供的文本和集群数据 Context.show_text_glyphs() 打电话。

注意：即使这个函数返回 False ，A Context.show_text_glyphs() 针对地面的行动仍将成功。它只会像一个 Context.show_glyphs() 操作。如果目标表面不使用utf-8文本和集群映射，用户可以使用此函数来避免计算它。

在 1.12.0 版本加入.

map_to_image(extents: RectangleInt | None) → ImageSurface

参数:

extents -- 将提取限制为矩形区域或 None 整个表面

返回:

新分配的图像表面

抛出:

Error --

返回图像表面，该图像表面是修改目标表面的后备存储的最有效机制。

注意，在映射原始曲面时将其用作目标或源是未定义的。多次映射曲面的结果未定义。打电话 Surface.finish() 在生成的图像表面上会导致未定义的行为。在图像表面未映射之前更改图像表面或表面的设备转换会导致未定义的行为。

呼叫方必须使用 Surface.unmap_image() 破坏这个图像表面。

在 1.15.0 版本加入.

mark_dirty() → None

告诉开罗已经画好了 表面 使用除开罗以外的其他方法，并且开罗应该重新读取任何缓存区域。注意你必须打电话 flush() 在画之前。

mark_dirty_rectangle(x: int, y: int, width: int, height: int) → None

参数:

• x -- 脏矩形的X坐标

• y -- 脏矩形的Y坐标

• width -- 脏矩形宽度

• height -- 脏矩形的高度

喜欢 mark_dirty() ，但只对指定的矩形进行了绘制，因此cairo可以保留曲面其他部分的缓存内容。

在上设置的任何缓存剪辑 表面 将通过此函数重置，以确保将来的cairo调用具有他们期望的剪辑集。

set_device_offset(x_offset: float, y_offset: float) → None

参数:

• x_offset -- X方向的偏移量，单位为设备单位

• y_offset -- Y方向的偏移量，单位为设备单位

设置在绘制时添加到CTM确定的设备坐标的偏移量 表面 . 这个函数的一个用例是当我们想要创建一个 表面 这将屏幕表面的一部分绘图重定向到屏幕外表面，而开罗API的用户完全看不到这种方式。通过设置转换 Context.translate() 不足以做到这一点，因为 Context.device_to_user() 将显示隐藏偏移。

请注意，偏移会影响绘制到曲面以及在源图案中使用曲面。

set_device_scale(x_scale: float, y_scale: float) → None

参数:

• x_scale -- X方向的比例因子

• y_scale -- Y方向的比例因子

设置一个比例，该比例与CTM绘制到曲面时确定的设备坐标相乘。这种方法的一个常见用途是以比例因子渲染到非常高分辨率的显示设备，因此假定1个像素为特定大小的代码仍然可以工作。通过设置转换 Context.translate() 不足以做到这一点，因为 Context.device_to_user() 将显示隐藏的比例。

在 1.14.0 版本加入.

set_fallback_resolution(x_pixels_per_inch: float, y_pixels_per_inch: float) → None

参数:

• x_pixels_per_inch -- 每英寸像素的水平设置

• y_pixels_per_inch -- 每英寸像素的垂直设置

设置图像回退的水平和垂直分辨率。

当后端本机不支持某些操作时，cairo将通过将操作呈现到一个映像上，然后将该映像覆盖到输出上进行回退。对于本机面向向量的后端，此函数可用于设置用于这些图像回退的分辨率（值越大，图像越详细，文件大小也越大）。

本机面向向量后端的一些示例是ps、pdf和svg后端。

对于本机以栅格为导向的后端，图像回退仍然是可能的，但它们始终以本机设备分辨率执行。所以这个函数对那些后端没有影响。

注意：回退解决方案仅在完成页面时生效（使用 Context.show_page() 或 Context.copy_page() ）因此，目前无法在单个页面上使用多个有效的回退解决方案。

在两个维度中，默认的回退分辨率都是每英寸300像素。

在 1.2 版本加入.

set_mime_data(mime_type: str, data: bytes) → None

参数:

• mime_type -- 图像数据的mime类型 (cairo.MIME_TYPE ）

• data -- 要附加到表面的图像数据

以格式附加图像 mime_type 到 表面 . 要从曲面中删除数据，请使用相同的mime类型调用此函数，然后 None 以获取数据。

附加的图像（或文件名）数据稍后可由支持它的后端（当前为：pdf、ps、svg和win32打印表面）使用，以发出此数据，而不是生成表面的快照。这种方法往往更快，需要更少的内存和磁盘空间。

可识别的mime类型列在下面 cairo.MIME_TYPE .

有关它可以处理哪些mime类型的详细信息，请参阅相应的后端surface docs。警告：如果以后在曲面上绘制，关联的mime数据将被丢弃。小心使用此功能。

在 1.12.0 版本加入.

show_page() → None

为支持多页的后端发出并清除当前页。使用 copy_page() 如果不想清除页面。

这有一个方便的函数 Context.show_page() .

在 1.6 版本加入.

supports_mime_type(mime_type: str) → bool

参数:

mime_type -- mime类型 (cairo.MIME_TYPE ）

返回:

True 如果Surface支持mime_类型， False 否则

返回表面是否支撑 mime_type .

在 1.12.0 版本加入.

write_to_png(fobj: cairo._FileLike | cairo._PathLike) → None

参数:

fobj -- 文件名或可写文件对象

加薪:

MemoryError 如果无法为操作分配内存

IOError 如果尝试写入文件时发生I/O错误

将内容写入 Surface 至 fobj 作为巴新的形象。 fobj 可以是文件名，也可以是以二进制模式打开的文件对象。

unmap_image(image: ImageSurface) → None

参数:

image -- 当前映射的图像

取消映射从返回的图像表面 Surface.map_to_image() .

图像的内容将上传到目标表面。之后，图像被销毁。

使用未返回的图像表面 Surface.map_to_image() 导致未定义的行为。

在 1.15.0 版本加入.

类ImageSurface (Surface ）

class cairo.ImageSurface(format: Format, width: int, height: int)

A cairo.ImageSurface 提供呈现到由cairo或调用代码分配的内存缓冲区的功能。支持的图像格式是在 cairo.Format .

__init__(format: Format, width: int, height: int) → None

参数:

• format -- 要创建的曲面中像素的格式

• width -- 表面宽度（像素）

• height -- 表面高度（像素）

返回:

一个新的 ImageSurface

创建一个 ImageSurface 指定的格式和尺寸。最初，表面内容物都是0。（具体来说，在每个像素中，属于格式的每个颜色或alpha通道将为0。像素内的位内容，但不属于给定格式，则未定义）。

classmethod create_for_data(data: memoryview, format: Format, width: int, height: int, stride: int = Ellipsis) → ImageSurface

参数:

• data -- 可写的python buffer/memoryview对象

• format -- 缓冲区中像素的格式

• width -- 要存储在缓冲区中的图像的宽度

• height -- 要存储在缓冲区中的图像的高度

• stride -- 缓冲区中各行开始之间分配的字节数。如果没有给出 cairo.Format.stride_for_width() 使用。

返回:

一个新的 ImageSurface

加薪:

MemoryError 如果没有记忆。

cairo.Error 如果无效 步幅 价值。

创建一个 ImageSurface 提供的像素数据。缓冲区的初始内容将用作初始图像内容；如果要清除缓冲区，必须使用cairo_rectangle（）和cairo_fill（）显式清除缓冲区。

请注意 步幅 可能大于每个像素的宽度*字节，以便为每个像素和行提供适当的对齐方式。此对齐方式需要允许在cairo内进行高性能渲染。获得合法步幅值的正确方法是调用 cairo.Format.stride_for_width() 使用所需的格式和最大图像宽度值，并使用生成的跨距值分配数据并创建 ImageSurface . 见 cairo.Format.stride_for_width() 例如代码。

classmethod create_from_png(fobj: cairo._PathLike | cairo._FileLike) → ImageSurface

参数:

fobj -- 一个 _PathLike 要加载的PNG的、文件或类似文件的对象。

返回:

一个新的 ImageSurface 已将内容初始化为给定的PNG文件。

创建新的图像曲面并将内容初始化为给定的PNG文件。 fobj 可以是文件名，也可以是以二进制模式打开的文件对象。

format_stride_for_width(width: int) → int

见 cairo.Format.stride_for_width() .

在 1.6 版本加入.

get_data() → memoryview

返回:

的数据的python缓冲区对象 ImageSurface ，用于直接检查或修改。在python 3上，返回一个memoryview对象。

在 1.2 版本加入.

get_format() → Format

返回:

的格式 ImageSurface .

返回类型:

cairo.Format

在 1.2 版本加入.

get_height() → int

返回:

的高度 ImageSurface 以像素为单位。

get_stride() → int

返回:

步伐 ImageSurface 以字节为单位。步幅是从图像数据的一行开始到下一行开始的距离（以字节为单位）。

get_width() → int

返回:

的宽度 ImageSurface 以像素为单位。

PDF类表面 (Surface ）

class cairo.PDFSurface(fobj: cairo._PathLike | cairo._FileLike, width_in_points: float, height_in_points: float)

pdf surface用于将cairo图形呈现为Adobe PDF文件，是一个多页矢量曲面后端。

在 1.2 版本加入.

__init__(fobj: cairo._PathLike | cairo._FileLike, width_in_points: float, height_in_points: float) → None

参数:

• fobj -- 文件名或可写文件对象。无可用于指定无输出。这将生成一个 PDFSurface 可以查询并用作源，而不生成临时文件。

• width_in_points -- 表面宽度，以点为单位（1点=1/72.0英寸）

• height_in_points -- 表面高度，以点为单位（1点=1/72.0英寸）

返回:

一个新的 PDFSurface 以要写入的点为单位的指定大小 fobj .

在 1.2 版本加入.

set_custom_metadata(name: str, value: str | None) → None

参数:

• name -- 要设置的自定义元数据项的名称。

• value -- 元数据的值。

设置自定义文档元数据。 name 可以是除PDF保留的以下名称之外的任何字符串：“标题”、“作者”、“主题”、“关键字”、“创建者”、“生产者”、“创建日期”、“修改日期”、“陷阱”。

如果 value 是 None 或空字符串，则 name 不会设置元数据。

例如：：

surface.set_custom_metadata("ISBN", "978-0123456789")

在 1.23.0 版本加入: 仅适用于开罗1.17.6+

set_size(width_in_points: float, height_in_points: float) → None

参数:

• width_in_points -- 新表面宽度，以点为单位（1点=1/72.0英寸）

• height_in_points -- 新表面高度，以点为单位（1点=1/72.0英寸）

更改的大小 PDFSurface 用于当前（及后续）页面。

仅应在对当前页执行任何绘图操作之前调用此函数。最简单的方法是在创建曲面后立即调用此函数，或者在使用 Context.show_page() 或 Context.copy_page() .

在 1.2 版本加入.

restrict_to_version(version: PDFVersion) → None

参数:

version -- PDF版本

将生成的PDF文件限制为版本。见 get_versions() 有关可在此处使用的可用版本值的列表。

仅应在对给定曲面执行任何绘图操作之前调用此函数。最简单的方法是在创建曲面后立即调用该函数。

在 1.12.0 版本加入.

static get_versions() → List[PDFVersion]

返回:

支持的版本列表

检索支持的版本列表。见 restrict_to_version() .

在 1.12.0 版本加入.

static version_to_string(version: PDFVersion) → str

参数:

version -- PDF版本

返回:

与给定版本关联的字符串

抛出:

ValueError -- 如果版本无效

获取给定版本ID的字符串表示形式。请参见 get_versions() 获取有效版本ID列表的方法。

在 1.12.0 版本加入.

add_outline(parent_id: int, utf8: str, link_attribs: str, flags: PDFOutlineFlags) → int

参数:

• parent_id -- 父项的ID或 PDF_OUTLINE_ROOT 如果这是顶级项目。

• utf8 -- 大纲的名称

• link_attribs -- 指定此大纲链接到的位置的链接属性

• flags -- 大纲项标志

返回:

添加项的ID。

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

set_metadata(metadata: PDFMetadata, utf8: str) → None

参数:

• metadata -- 要设置的元数据项。

• utf8 -- 元数据值

设置文档元数据。这个 PDFMetadata.CREATE_DATE 和 PDFMetadata.MOD_DATE 值必须采用ISO-8601格式：yyyy-mm-ddthh:mm:ss。表单的可选时区” [+/-] 可以附加UTC时间的hh:mm“或”z“。所有其他元数据值都可以是任何utf-8字符串。

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

set_page_label(utf8: str) → None

参数:

utf8 -- 元数据值

设置当前页的页标签。

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

set_thumbnail_size(width: int, height: int) → None

参数:

• width -- 缩略图宽度。

• height -- 缩略图高度

设置当前页面和所有后续页面的缩略图图像大小。将宽度或高度设置为0将禁用当前页和后续页的缩略图。

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

PSSurface类 (Surface ）

class cairo.PSSurface(fobj: cairo._FileLike | cairo._PathLike, width_in_points: float, height_in_points: float)

这个 PSSurface 用于将cairo图形呈现为Adobe PostScript文件，是一个多页矢量曲面后端。

__init__(fobj: cairo._FileLike | cairo._PathLike, width_in_points: float, height_in_points: float) → None

参数:

• fobj -- 文件名或可写文件对象。无可用于指定无输出。这将生成一个 PSSurface 可以查询并用作源，而不生成临时文件。

• width_in_points -- 表面宽度，以点为单位（1点=1/72.0英寸）

• height_in_points -- 表面高度，以点为单位（1点=1/72.0英寸）

返回:

一个新的 PDFSurface 以要写入的点为单位的指定大小 fobj .

加薪:

MemoryError 如果没有记忆

请注意，PostScript输出的各个页面的大小可能会有所不同。见 set_size() .

dsc_begin_page_setup() → None

此方法指示后续调用 dsc_comment() 应将注释定向到PostScript输出的页面设置部分。

此方法调用仅适用于曲面的第一页。它应该在接到任何电话后呼叫 dsc_begin_setup() 在对表面进行任何绘图之前。

见 dsc_comment() 了解更多详细信息。

在 1.2 版本加入.

dsc_begin_setup() → None

此函数指示后续调用 dsc_comment() 应将注释直接指向PostScript输出的设置部分。

每个曲面最多应调用一次此函数，并且必须在调用 dsc_begin_page_setup() 在对表面进行任何绘图之前。

见 dsc_comment() 了解更多详细信息。

在 1.2 版本加入.

dsc_comment(comment: str) → None

参数:

comment -- 要发送到PostScript输出中的注释字符串

将注释发射到给定曲面的PostScript输出中。

该注释应符合PostScript语言文档结构约定（DSC）。有关可用注释及其含义的详细信息，请参阅该手册。尤其是，%includeFeature注释允许使用与设备无关的方法来控制打印机设备功能。因此，PostScript打印机说明文件规范也将是一个有用的参考。

注释字符串必须以百分比字符（%）开头，并且字符串的总长度（包括任何初始百分比字符）不得超过255个字符。违反上述任何一个条件都会导致 PSSurface 进入错误状态。但除了这两个条件外，这个函数不会强制注释与任何特定规范的一致性。

注释字符串不应有尾随新行。

DSC指定可以显示特定注释的不同部分。此函数提供在三个部分中发出的注释：标题、设置部分和页面设置部分。前两节中出现的注释适用于整个文档，而BeginPageSetup节中的注释仅适用于单个页面。

对于要在标题部分中显示的注释，应在创建曲面后调用此函数，但在调用 dsc_begin_setup() .

若要在“设置”部分中显示注释，应在调用 dsc_begin_setup() 但在接到电话之前 dsc_begin_page_setup() .

若要在“页面设置”部分中显示注释，应在调用 dsc_begin_page_setup() .

注意，只需要打电话 dsc_begin_page_setup() 任何表面的第一页。在打电话给 Context.show_page() 或 Context.copy_page() 注释被明确地定向到当前页面的页面设置部分。但是在每一页的开头调用这个函数并不会造成伤害，因为这种一致性可能会使调用代码更简单。

最后一点，开罗会自动生成几个注释。因此，应用程序不得手动生成以下任何注释：

标题部分：%！PS-Adobe-3.0，%创建者，%创建日期，%页面，%边界框，%文档数据，%语言级别，%结束注释。

安装节：%BeginSetup，%EndSetup

页面设置节：%BeginPageSetup，%PageBoundingBox，%EndPageSetup。

其他节：%beginprolog%，endprolog%，page%，trailer%，eof

下面是一个示例序列，演示如何使用此函数：

surface = PSSurface (filename, width, height)
...
surface.dsc_comment (surface, "%%Title: My excellent document")
surface.dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover")
...
surface.dsc_begin_setup (surface)
surface.dsc_comment (surface, "%%IncludeFeature: *MediaColor White")
...
surface.dsc_begin_page_setup (surface)
surface.dsc_comment (surface, "%%IncludeFeature: *PageSize A3")
surface.dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity")
surface.dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy")
surface.dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue")
... draw to first page here ..
ctx.show_page (cr)
...
surface.dsc_comment (surface, "%%IncludeFeature:  PageSize A5");
...

在 1.2 版本加入.

get_eps() → bool

返回:

真的如果 PSSurface 将输出封装的PostScript。

在 1.6 版本加入.

static level_to_string(level: PSLevel) → str

参数:

level -- PS级

返回:

与给定级别关联的字符串。

获取给定的字符串表示形式 水平 . 见 get_levels() 获取有效级别ID列表的方法。

备注

2012年1月12日之前，可在 ps_level_to_string()

在 1.12.0 版本加入.

static ps_level_to_string(level: PSLevel) → str

Alias level_to_string()

在 1.6 版本加入.

restrict_to_level(level: PSLevel) → None

参数:

level -- PS级

将生成的PostScript文件限制为 水平 . 见 get_levels() 有关可在此处使用的可用级别值的列表。

仅应在对给定曲面执行任何绘图操作之前调用此函数。最简单的方法是在创建曲面后立即调用该函数。

在 1.6 版本加入.

set_eps(eps: bool) → None

参数:

eps -- 输出EPS格式PostScript为真

如果 eps 如果为真，PostScript表面将输出封装的PostScript。

仅应在对当前页执行任何绘图操作之前调用此函数。最简单的方法是在创建曲面后立即调用该函数。封装的PostScript文件不应包含多个页面。

在 1.6 版本加入.

set_size(width_in_points: float, height_in_points: float) → None

参数:

• width_in_points -- 新表面宽度，以点为单位（1点=1/72.0英寸）

• height_in_points -- 新表面高度，以点为单位（1点=1/72.0英寸）

更改当前（及后续）页面的PostScript图面大小。

仅应在对当前页执行任何绘图操作之前调用此函数。最简单的方法是在创建曲面后立即调用此函数，或者在使用 Context.show_page() 或 Context.copy_page() .

在 1.2 版本加入.

static get_levels() → List[PSLevel]

返回:

支持的级别列表

检索支持的级别列表。见 restrict_to_level() .

在 1.12.0 版本加入.

类记录表面 (Surface ）

class cairo.RecordingSurface(content: Content, rectangle: Rectangle)

A RecordingSurface 是在曲面后端接口的最高级别（即，绘制、遮罩、笔划、填充和显示_文本_glyphs的级别）记录所有绘图操作的曲面。然后，可以将记录面用作源面，以“重放”任何目标面。

如果要重放一个表面，以便目标中的结果与应用于记录表面的原始操作而不是应用于目标表面时获得的结果相同，则可以使用如下代码：

cr = cairo.Context(target)
cr.set_source_surface(recording_surface, 0.0, 0.0)
cr.paint()

A RecordingSurface 在逻辑上是无边界的，即它对绘图表面的大小没有隐式约束。然而，在实践中，这很少有用，因为您希望对具有已知边界的特定目标曲面进行重放。对于这种情况，在创建时指定记录曲面的目标范围更为有效。

记录表面的记录阶段小心地快照所有必要的对象（路径、模式等），以实现精确的重放。

在 1.11.0 版本加入.

__init__(content: Content, rectangle: Rectangle) → None

参数:

• content -- 新表面的内容

• rectangle -- 或无记录无边界操作。

创建一个 RecordingSurface 它可用于记录最高级别的所有绘图操作（即，绘制、遮罩、笔划、填充和显示_文本_glyphs的级别）。这个 RecordingSurface 然后可以对任何目标曲面“重放”，将其用作绘制操作的源。

的记录阶段 RecordingSurface 小心地快照所有必要的对象（路径、模式等），以实现精确的重播。

在 1.11.0 版本加入.

ink_extents() → Tuple[float, float, float, float]

• X0:墨迹边框左上角的X坐标

• y0:墨迹边框左上角的y坐标

• 宽度：墨迹边框的宽度

• 高度：墨迹边界框的高度

测量存储在 RecordingSurface . 这对于计算 ImageSurface （或等效物）在其中重放绘图操作的完整序列。

在 1.11.0 版本加入.

get_extents() → Rectangle | None

返回:

矩形或 None 如果表面没有边界。

获取记录表面的范围。

在 1.12.0 版本加入.

SvgSurface类 (Surface ）

class cairo.SVGSurface(fobj: cairo._PathLike | cairo._FileLike, width_in_points: float, height_in_points: float)

这个 SVGSurface 用于将cairo图形呈现为SVG文件，是一个多页矢量曲面后端

__init__(fobj: cairo._PathLike | cairo._FileLike, width_in_points: float, height_in_points: float) → None

参数:

• fobj -- 文件名或可写文件对象。无可用于指定无输出。这将生成一个 SVGSurface 可以查询并用作源，而不生成临时文件。

• width_in_points -- 表面宽度，以点为单位（1点=1/72.0英寸）

• height_in_points -- 表面高度，以点为单位（1点=1/72.0英寸）

restrict_to_version(version: SVGVersion) → None

参数:

version -- SVG版本

将生成的SVG文件限制为版本。见 get_versions() 有关可在此处使用的可用版本值的列表。

仅应在对给定曲面执行任何绘图操作之前调用此函数。最简单的方法是在创建曲面后立即调用该函数。

在 1.12.0 版本加入.

static get_versions() → List[SVGVersion]

返回:

支持的版本列表

检索支持的版本列表。见 restrict_to_version() .

在 1.12.0 版本加入.

static version_to_string(version: SVGVersion) → str

参数:

version -- SVG版本

返回:

与给定版本关联的字符串

抛出:

ValueError -- 如果版本无效

获取给定版本ID的字符串表示形式。请参见 get_versions() 获取有效版本ID列表的方法。

在 1.12.0 版本加入.

get_document_unit() → SVGUnit

返回:

SVG曲面的SVG单元。

返回类型:

SVGUnit

获取SVG曲面的单位。

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

set_document_unit(unit: SVGUnit) → None

参数:

unit (SVGUnit) -- SVG单元

使用指定的单位表示生成的SVG文件的宽度和高度。见 SVGUnit 有关可在此处使用的可用单位值的列表。

在生成SVG文件之前，可以随时调用此函数。

但是，为了尽量减少模棱两可的风险，建议在给定表面上进行任何绘图操作之前调用它，以便更清楚绘图操作中使用的单位。

最简单的方法是在创建SVG曲面后立即调用该函数。

注意：如果从未调用此函数，cairo生成的SVG文档的默认单位将为“pt”。这是出于历史原因。

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

win32surface类 (Surface ）

class cairo.Win32Surface(hdc: int)

Microsoft Windows Surface用于将cairo图形呈现到Microsoft Windows、位图和打印设备上下文。

__init__(hdc: int) → None

参数:

hdc (int) -- 为创建曲面

创建针对给定DC的cairo曲面。将查询DC的初始剪辑范围，并将其用作cairo曲面的大小。生成的曲面将始终采用cairo.format_rgb24格式，请参见 cairo.Format .

win32printingsurface类 (Surface ）

class cairo.Win32PrintingSurface(hdc: int)

win32printingsurface是一种多页向量曲面类型。

__init__(hdc: int) → None

参数:

hdc -- 为创建曲面

返回:

新创建的曲面

创建针对给定DC的cairo曲面。将查询DC的初始剪辑范围，并将其用作cairo曲面的大小。DC应该是一个打印DC；抗锯齿将被忽略，并且将尽可能多地使用GDI绘制到表面。

将使用分页表面包裹返回的表面，以提供正确的复杂渲染行为； cairo.Surface.show_page() 和相关的方法必须用于正确的输出。

XCBsurface类 (Surface ）

class cairo.XCBSurface(connection: Any, drawable: Any, visualtype: Any, width: int, height: int)

xcb表面用于使用xcb库将cairo图形呈现到x窗口系统窗口和pixmap。

请注意，如果XCB曲面可用，它会自动利用X渲染扩展。

__init__(connection: Any, drawable: Any, visualtype: Any, width: int, height: int) → None

参数:

• connection -- XCB连接

• drawable -- A x可牵引

• visualtype -- X视觉类型

• width -- 表面宽度

• height -- 表面高度

创建针对给定可绘制对象（pixmap或窗口）的cairo曲面。

备注

未实现此类型。如果你需要的话，请把它归档。

set_size(width: int, height: int) → None

参数:

• width -- 表面的宽度

• height -- 表面高度

通知cairo表面下的新尺寸x可绘图。对于为窗口（而不是PixMap）创建的曲面，每次窗口大小更改时都必须调用此函数。（对于子窗口，通常是您自己调整窗口大小，但对于顶级窗口，必须侦听配置事件。）

PixMap永远无法更改大小，因此不需要在为PixMap创建的曲面上调用此函数。

XLI类表面 (Surface ）

class cairo.XlibSurface

xlib表面用于使用xlib库将cairo图形呈现到x窗口系统窗口和pixmaps。

请注意，XLib曲面自动利用X渲染扩展（如果它可用）。

备注

XlibSurface 无法直接实例化，因为与xlib的python交互将需要到提供C API的xlib的开源python绑定。然而，一个 XlibSurface 使用pygtk http://www.pygtk.org/时，可以从函数调用返回实例。

get_depth() → int

返回:

用于表示每个像素值的位数。

在 1.2 版本加入.

get_height() → int

返回:

以像素为单位的表面下的X可绘制高度。

在 1.2 版本加入.

get_width() → int

返回:

以像素为单位的表面下的X可绘制宽度。

在 1.2 版本加入.

类脚本表面 (Surface ）

class cairo.ScriptSurface(script: ScriptDevice, content: Content, width: float, height: float)

脚本表面提供了渲染到与cairo绘图模型匹配的本机脚本的能力。可以使用util/cairo脚本目录下的工具或使用cairo perf trace重播脚本。

在 1.14 版本加入.

__init__(script: ScriptDevice, content: Content, width: float, height: float) → None

参数:

• script -- 脚本（输出设备）

• content -- 表面的含量

• width -- 宽度（像素）

• height -- 高度（像素）

抛出:

cairo.Error --

创建一个新曲面，该曲面将通过 script .

classmethod create_for_target(script: ScriptDevice, target: Surface) → ScriptSurface

参数:

• script -- 脚本（输出设备）

• target -- 要包装的目标表面

抛出:

cairo.Error --

创建将渲染到的代理曲面 target 并将操作记录到 device .

在 1.14 版本加入.

类T型面 (Surface ）

class cairo.TeeSurface(master: Surface)

此曲面支持将其所有输入重定向到多个曲面。

在 1.14 版本加入.

__init__(master: Surface) → None

add(target: Surface) → None

参数:

target --

抛出:

cairo.Error --

添加表面

在 1.14 版本加入.

remove(target: Surface) → None

参数:

target --

抛出:

cairo.Error --

去除表面

在 1.14 版本加入.

index(index: int) → Surface

参数:

index --

抛出:

cairo.Error --

返回索引处的曲面 index . 主曲面位于索引0处。

在 1.14 版本加入.