[TOC] # **pygame.Surface** Pygame 中用于表示圖像的對象。 Surface((width, height), flags=0, depth=0, masks=None) -> Surface Surface((width, height), flags=0, Surface) -> Surface ## **屬性 & 方法** * pygame.Surface.blit() — 將一個圖像（Surface 對象）繪制到另一個圖像上方 * pygame.Surface.convert() — 修改圖像（Surface 對象）的像素格式 * pygame.Surface.convert\_alpha() — 修改圖像（Surface 對象）的像素格式，包含 alpha 通道 * pygame.Surface.copy() — 創建一個 Surface 對象的拷貝 * pygame.Surface.fill() — 使用純色填充 Surface 對象 * pygame.Surface.scroll() — 移動 Surface 對象 * pygame.Surface.set\_colorkey() — 設置 colorkeys * pygame.Surface.get\_colorkey() — 獲取 colorkeys * pygame.Surface.set\_alpha() — 設置整個圖像的透明度 * pygame.Surface.get\_alpha() — 獲取整個圖像的透明度 * 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() — 獲取 Surface 對象 8 位索引的調色板 * pygame.Surface.get\_palette\_at() — 返回給定索引號在調色板中的顏色值 * pygame.Surface.set\_palette() — 設置 Surface 對象 8 位索引的調色板 * pygame.Surface.set\_palette\_at() — 設置給定索引號在調色板中的顏色值 * pygame.Surface.map\_rgb() — 將一個 RGBA 顏色轉換為映射的顏色值 * pygame.Surface.unmap\_rgb() — 將一個映射的顏色值轉換為 Color 對象 * pygame.Surface.set\_clip() — 設置該 Surface 對象的當前剪切區域 * pygame.Surface.get\_clip() — 獲取該 Surface 對象的當前剪切區域 * pygame.Surface.subsurface() — 根據父對象創建一個新的子 Surface 對象 * pygame.Surface.get\_parent() — 獲取子 Surface 對象的父對象 * pygame.Surface.get\_abs\_parent() — 獲取子 Surface 對象的頂層父對象 * pygame.Surface.get\_offset() — 獲取子 Surface 對象在父對象中的偏移位置 * pygame.Surface.get\_abs\_offset() — 獲取子 Surface 對象在頂層父對象中的偏移位置 * 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 對象具有固定的分辨率和像素格式。Surface 對象通過 8 位索引調色板的 24 位色彩。 只需要指定尺寸，就能調用 pygame.Surface() 創建一個新的圖像對象，創建出來的 Surface 默認是全黑色。如果沒有指定其他參數，將創建出最適合當前顯示器的 Surface 對象。 像素格式可以通過傳遞 depth 參數或一個已存在的 Surface 對象來控制。flags 參數是 Surface 對象額外功能的掩碼。你可以傳遞任何下列標志的組合： | HWSURFACE | 將創建出來的 Surface 對象存放于顯存中 | | --- | --- | | SRCALPHA | 每個像素包含一個 alpha 通道 | 只能使用兩個 flags 中的一個，并且無法支持所有的顯示和格式。 高級用法可以結合 masks 和 depth 參數，masks 是由 4 個整數組（溫馨提示：(R, G, B, A)），將于每個像素的顏色進行按位與計算。通常，Surface 對象不需要 masks 參數。 Surface 對象可以擁有許多其他額外的屬性，例如 alpha 通道（控制透明度），colorkeys，源矩形剪切等。這些功能主要在一個 Surface 對象上繪制另一個 Surface 對象時發揮作用。 Pygame 在繪制時將會盡可能的嘗試硬件加速，否則采用高度優化的繪制方式實現。 Pygame 支持三種透明度類型：colorkeys，surface alphas 和 pixel alphas（溫馨提示：colorkeys 是指設置圖像中的某個顏色值為透明，surface alphas 是調整整個圖像的透明度，pixel alphas 則是獨立設置圖像中每一個像素的透明度）。surface alphas 可以和 colorkeys 混合使用，而 pixel alphas 不能和其他兩個混合。 溫馨提示： * colorkeys 是設置圖像中的某個顏色值為透明（任何像素的顏色值只要跟 colorkeys 的值相同即被設置為透明）； * surface alphas 是調整整個圖像的透明度，范圍是 0 ~ 255（0 表示完全透明，255 表示完全不透明）； * pixel alphas 是為圖像中的每個像素設置一個獨立的值，用于存放該像素的透明度。這是最精確的透明度設置，但也是最慢的。 Surface 對象支持像素訪問。像素訪問在硬件上實現的速度是很慢的，也不推薦大家這么做（但任性的 Pygame 還是提供了訪問的途徑……）。可以使用 get\_at() 和 set\_at() 方法獲取和設置像素。簡單的使用它們來訪問某些像素是可以的，但如果用它們來進行所有的像素訪問操作就會變得相當緩慢。 如果你打算做很多像素級別的操作，那么還是建議你使用 PixelArray 模塊的方法，因為它提供了類似數組的方式來訪問 Surface 對象上的像素。對于涉及數學運算的范圍，建議使用 surfarray 模塊，這個模塊主要用于數學運算，因此速度很快，但需要 Numpy 模塊的支持（溫馨提示，NumPy 下載地址：[https://pypi.python.org/pypi/numpy/#downloads](https://pypi.python.org/pypi/numpy/#downloads)） 任何函數如果需要訪問 Surface 對象，需要將 Surface 先 lock()。這些函數可以獨立 lock() 和 unlock() Surface 對象。但如果這些函數多次調用，就會有很多額外的上鎖和解鎖操作。最好的方法是在調用前先手動上鎖，然后再完成所有調用后再手動解鎖。所有需要鎖定 Surface 對象的函數都在它們的文檔中有仔細說明。一般情況下，完成函數的調用后要記得解鎖哦^\_^ Surface 對象內部會將像素的所有顏色重新編碼為單一的數字。使用 map\_rgb() 和 unmap\_rgb() 方法可以手動地進行轉換。 Surface 對象也可以引用部分其他 Surface 對象的內容。使用 subsurface() 方法創建即可創建子對象，其中任何 Surface 對象的改變均會影響到其他子對象。 每個 Surface 對象含有一個剪切區域，默認的剪切區域是整個對象表面。如果修改剪切區域，那么所有的繪制操作將只在剪切區域中生效。 ## **屬性 & 方法詳解** ### **blit()** 將一個圖像（Surface 對象）繪制到另一個圖像上方。 blit(source, dest, area=None, special\_flags = 0) -> Rect 將 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 對象，表示實際繪制的矩形區域。 注意1：當繪制到一個 8 位的 Surface 對象上時，pixel alphas 會被忽略。 注意2：通過 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 對象的尺寸，你將看不到移動的結果，但并不會出錯。 很多人可能會“想當然的”理解所謂的“移動”就是簡單的移動圖像到一個新的位置，其實這個方法并不是這樣的…… 請看，好好的一個 LOGO：  向右、向下移動 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 為圖像的尺寸。 你可以給該函數傳遞關鍵字參數，返回的結果將受參數的影響。 例如： ~~~ # 圖像的尺寸為 100 * 100 image = pygame.image.load("fishc.png").convert_alpha() print(image.get_rect()) print(image.get_rect(center=(20, 20))) print(image.get_rect()) ~~~ 打印的結果是： ~~~ >>> <rect(0, 0, 100, 100)> <rect(-30, -30, 100, 100)> <rect(0, 0, 100, 100)> ~~~ ### **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(=‘2’) -> BufferProxy 返回一個 BufferProxy 對象，它用 C 級別的數組結構輸出 Surface 對象內部的像素緩沖區，Python 級別的數組或 C 級別的緩沖區作為接口。輸出的像素緩沖區是可寫的。新的緩沖區協議支持 Python 2.6 以上和 CPython。舊的緩沖區協議也支持 Python 2.x。舊的緩沖區數據是由一個 =’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 新增加的。 ### **\_pixels\_address** 像素緩沖區地址。 \_pixels\_address -> int 該 Surface 對象原始像素的字節起始地址。 Pygame 1.9.2 新增加的。