表面

類表面（）

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() → Optional[Device]

返回:

設備或 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) → Optional[bytes]

參數:

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: Optional[RectangleInt]) → 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: Union[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: Union[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() → bytes

返回:

步伐 ImageSurface 以字節為單位。步幅是從圖像數據的一行開始到下一行開始的距離（以字節為單位）。

get_width() → int

返回:

的寬度 ImageSurface 以像素為單位。

PDF類表面 (Surface ）

class cairo.PDFSurface(fobj: Union[cairo._PathLike, cairo._FileLike], width_in_points: float, height_in_points: float)

pdf surface用于將cairo圖形呈現為Adobe PDF文件，是一個多頁矢量曲面后端。

在 1.2 版本加入.

__init__(fobj: Union[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_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: Union[cairo._FileLike, cairo._PathLike], width_in_points: float, height_in_points: float)

這個 PSSurface 用于將cairo圖形呈現為Adobe PostScript文件，是一個多頁矢量曲面后端。

__init__(fobj: Union[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() → Optional[Rectangle]

返回:

矩形或 None 如果表面沒有邊界。

獲取記錄表面的范圍。

在 1.12.0 版本加入.

SvgSurface類 (Surface ）

class cairo.SVGSurface(fobj: Union[cairo._PathLike, cairo._FileLike], width_in_points: float, height_in_points: float)

這個 SVGSurface 用于將cairo圖形呈現為SVG文件，是一個多頁矢量曲面后端

__init__(fobj: Union[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繪圖模型匹配的本機腳本的能力?？梢允褂胾til/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 版本加入.