[TOC] # **pygame.display** Pygame 中用于控制窗口和屏幕顯示的模塊。 注：為了適應語境，display 在該文檔中有時翻譯為“顯示”，有時翻譯為“顯示界面”。 ## **函數** * pygame.display.init() — 初始化 display 模塊 * pygame.display.quit() — 結束 display 模塊 * pygame.display.get\_init() — 如果 display 模塊已經初始化，返回 True * pygame.display.set\_mode() — 初始化一個準備顯示的窗口或屏幕 * pygame.display.get\_surface() — 獲取當前顯示的 Surface 對象 * pygame.display.flip() — 更新整個待顯示的 Surface 對象到屏幕上 * pygame.display.update() — 更新部分軟件界面顯示 * pygame.display.get\_driver() — 獲取 Pygame 顯示后端的名字 * pygame.display.Info() — 創建有關顯示界面的信息對象 * pygame.display.get\_wm\_info() — 獲取關于當前窗口系統的信息 * pygame.display.list\_modes() — 獲取全屏模式下可使用的分辨率 * pygame.display.mode\_ok() — 為顯示模式選擇最合適的顏色深度 * pygame.display.gl\_get\_attribute() — 獲取當前顯示界面 OpenGL 的屬性值 * pygame.display.gl\_set\_attribute() — 設置當前顯示模式的 OpenGL 屬性值 * pygame.display.get\_active() — 當前顯示界面顯示在屏幕上時返回 True * pygame.display.iconify() — 最小化顯示的 Surface 對象 * pygame.display.toggle\_fullscreen() — 切換全屏模式和窗口模式 * pygame.display.set\_gamma() — 修改硬件顯示的 gama 坡道 * pygame.display.set\_gamma\_ramp() — 自定義修改硬件顯示的 gama 坡道 * pygame.display.set\_icon() — 修改顯示窗口的圖標 * pygame.display.set\_caption() — Set the current window caption * pygame.display.get\_caption() — Get the current window caption * pygame.display.set\_palette() — Set the display color palette for indexed displays 這個模塊提供控制 Pygame 顯示界面（display）的各種函數。Pygame 的 Surface 對象即可顯示為一個窗口，也可以全屏模式顯示。當你創建并顯示一個常規的 Surface 對象后，在該對象上的改變并不會立刻反映到可見屏幕上，你必須選擇一個翻轉函數來顯示改動后的畫面。 顯示的原點是 (x=0, y=0) 的位置，及屏幕的左上角，坐標軸向右下角增長。 Pygame 的 display 事實上可以有幾種初始化的方式。默認情況下，display 作為一個軟件驅動的幀緩沖區。除此之外，你可以使用硬件加速和 OpenGL 支持的特殊模塊。這些是通過給 pygame.display.set\_mode() 傳入 flags 參數來控制的。 Pygame 在任何時間內都只允許有一個顯示界面。使用 pygame.display.set\_mode() 創建的新顯示界面會自動替換掉舊的。如果需要精確控制像素格式或顯示分辨率，使用 pygame.display.mode\_ok()，pygame.display.list\_modes()，和 pygame.display.Info() 來查詢顯示界面相關的信息。 一旦 Surface 對象的顯示界面被創建出來，這個模塊的函數就只影響當前的顯示界面。如果該模塊未初始化， Surface 對象也會變為“非法”。如果新的顯示模式被設置，當前的 Surface 對象將會自動切換到新的顯示界面。 當一個新的顯示模式被設置，會在 Pygame 的事件隊列中放入幾個相關事件。當用于希望關閉程序時，pygame.QUIT 事件會被發送；當顯示界面獲得和失去焦點時，窗口會得到 pygame.ACTIVEEVENT 事件；如果顯示界面設置了 pygame.RESIZABLE 標志，那么當用戶調整窗口尺寸時，pygame.VIDEORESIZE 事件會被發送；硬件顯示指當接收到 pygame.VIDEOEXPOSE 事件時，將部分需要被重繪的窗口直接繪制到屏幕上。 一些顯示環境擁有自動拉伸所有窗口的選項。當該選項被啟動時，自動拉伸會扭曲 Pygame 窗口的外觀。在 Pygame 的例子目錄中，有一個演示代碼（prevent\_display\_stretching.py）展示如何在微軟系統（Vista 以上系統）中關閉 Pygame 顯示的自動拉伸屬性。 ## **函數詳解** ### **pygame.display.init()** 初始化 display 模塊。 init() -> None 初始化 Pygame 的 display 模塊。在初始化之前，display 模塊無法做任何事情。但當你調用更高級別的 pygame.init()，變會自動調用 pygame.display.init() 進行初始化。 初始化后，Pygame 將自動從幾個內部的顯示后端中選擇一個。顯示模式由平臺和當前用戶權限決定。在 display 模塊被初始化之前，可以通過環境變量 SDL\_VIDEODRIVER 設置哪一個顯示后端將被使用。具有多種顯示后端的系統如下： > Windows : windib, directx Unix : x11, dga, fbcon, directfb, ggi, vgl, svgalib, aalib 在一些平臺上，可以將 Pygame 的 display 嵌入到已經存在的窗口中。如果這么做，環境變量 SDL\_WINDOWID 必須被設置為一個包含窗口 ID 或句柄的字符串。當 Pygame 的 display 被初始化的時候，將檢測環境變量。注意，在一個運行的窗口嵌入 display 會產生許多奇怪的副作用。 多次調用該函數并沒有任何問題，但也不會有什么效果。 ### **pygame.display.quit()** 結束 display 模塊。 quit() -> None 這個函數會關閉整個 display 模塊。這將意味著任何一個活躍的顯示界面都將被關閉。當主程序退出時，該函數也會被自動調用。 多次調用該函數并沒有任何問題，但也不會有什么效果。 ### **pygame.display.get\_init()** 如果 display 模塊已經初始化，返回 True。 get\_init() -> bool 如果 display 模塊已經初始化，返回 True。 ### **pygame.display.set\_mode()** 初始化一個準備顯示的窗口或屏幕。 set\_mode(resolution=(0,0), flags=0, depth=0) -> Surface 這個函數將創建一個 Surface 對象的顯示界面。傳入的參數用于指定顯示類型。最終創建出來的顯示界面將是最大可能地匹配當前操作系統。 resolution 參數是一個二元組，表示寬和高。flags 參數是附件選項的集合。depth 參數表示使用的顏色深度。 返回的 Surface 對象可以像常規的 Surface 對象那樣去繪制，但發生的改變最終會顯示到屏幕上。 如果沒有傳入 resolution 參數，或者使用默認設置 (0, 0)，且 Pygame 使用 SDL1.2.10 以上版本，那么創建出來的 Surface 對象將與當前屏幕用戶一樣的分辨率。如果只有寬或高其中一項被設置為 0，那么 Surface 對象將使用屏幕分辨率的寬或高代替它。如果 SDL 版本低于 1.2.10，那么將拋出異常。 通常來說，最好的做法是不要傳遞 depth 參數。因為默認 Pygame 會根據當前操作系統選擇最好和最快的顏色深度。如果你的游戲確實需要一個特殊的顏色格式，那么你可以通過控制 depth 參數來實現。Pygame 將為模擬一個非現成的顏色深度而耗費更多的時間。 當使用全屏顯示模式的時候，有時候無法完全匹配到需要的分辨率。在這種情況下，Pygame 將自動選擇最匹配的分辨率使用，而返回的 Surface 對象將保持與需求的分辨率一致。 flags 參數指定你想要的顯示類型。提供幾個選擇給你，你可以通過位操作同時使用多個類型（管道操作符 “|”）。如果你傳入 0 或沒有傳入 flags 參數，默認會使用軟件驅動窗口。這兒是 flags 參數提供的幾個可選項： | **選項** | **含義** | | --- | --- | | pygame.FULLSCREEN | 創建一個全屏顯示 | | pygame.DOUBLEBUF | 1\. 雙緩沖模式 2. 推薦和 HWSURFACE 或 OPENGL 一起使用 | | pygame.HWSURFACE | 硬件加速，只有在 FULLSCREEN 下可以使用 | | pygame.OPENGL | 創建一個 OPENGL 渲染的顯示 | | pygame.RESIZABLE | 創建一個可調整尺寸的窗口 | | pygame.NOFRAME | 創建一個沒有邊框和控制按鈕的窗口 | 舉個例子： ~~~ # 在屏幕中創建一個 700 * 400 的窗口screen_width=700screen_height=400screen=pygame.display.set_mode([screen_width, screen_height]) ~~~ ### **pygame.display.get\_surface()** 獲取當前顯示的 Surface 對象。 get\_surface() -> Surface 返回當前顯示的 Surface 對象。如果沒有設置任何顯示模式，那么返回 None。 ### **pygame.display.flip()** 更新整個待顯示的 Surface 對象到屏幕上。 flip() -> None 這個函數將更新整個顯示界面的內容。如果你的顯示模式使用了 pygame.HWSURFACE（硬件加速）和 pygame.DOUBLEBUF（雙緩沖）標志，那么將等待垂直會掃并切換顯示界面。如果你使用不同類型的顯示模式，那么它將簡單的更新整個顯示界面的內容。 當使用 pygame.OPENGL（使用 OPENGL 渲染）顯示模式時，將創建一個 gl 緩沖切換區。 溫馨提示：垂直回掃是與視頻顯示相關的時間測量，它代表了一個幀的結束和下一幀的開始時間之間的時間間隔。 ### **pygame.display.update()** 更新部分軟件界面顯示。 update(rectangle=None) -> None update(rectangle\_list) -> None 這個函數可以看作是 pygame.display.flip() 函數在軟件界面顯示的優化版。它允許更新屏幕的部分內容，而不必完全更新。如果沒有傳入任何參數，那么該函數就像 pygame.display.flip() 那樣更新整個界面。 你可以傳遞一個或多個矩形區域給該函數。一次性傳遞多個矩形區域比多次傳遞更有效率。如果傳入的是一個空列表或者 None，那么將忽略參數。 該函數不能在 pygame.OPENGL 顯示模式下調用，否則會拋出異常。 ### **pygame.display.get\_driver()** 獲取 Pygame 顯示后端的名字。 get\_driver() -> name 初始化的時候，Pygame 會從多個可用的顯示后端中選擇一個。這個函數返回顯示后端內部使用的名字。可以用來提供有關顯示性能加速的一些信息。可以參考 pygame.display.set\_mode() 的 SDL\_VIDEODRIVER 環境變量。 ### **pygame.display.Info()** 創建有關顯示界面的信息對象。 Info() -> VideoInfo 創建一個對象，包含對當前圖形環境一些屬性的描述。在一些平臺上，如果這個函數在 pygame.display.set\_mode() 前被調用，可以提供一些關于默認顯示模式的信息。也可以在設置完顯示模式后調用該函數，以確認顯示選項是否如愿以償。 返回的 VideoInfo 對象包含以下這些屬性： | **屬性** | **含義** | | --- | --- | | hw | 如果是 True，則表示啟用硬件加速 | | wm | 如果是 True，則表示顯示窗口模式 | | video\_mem | 表示顯存是多少兆字節（mb），0 表示不清楚 | | bitsize | 表示每個像素存放多少位 | | bytesize | 表示每個像素存放多少字節 | | masks | 4 個值用于打包像素的 RGBA 值 | | shifts | 4 個值用于打包像素的 RGBA 值 | | losses | 4 個值用于打包像素的 RGBA 值 | | blit\_hw | 如果是 True，則表示加速硬件驅動的 Surface 對象繪制 | | blit\_hw\_CC | 如果是 True，則表示加速硬件驅動的 Surface 對象 colorkey 繪制 | | blit\_hw\_A | 如果是 True，則表示加速硬件驅動的 Surface 對象 pixel alpha 繪制 | | blit\_sw | 如果是 True，則表示加速軟件驅動的 Surface 對象繪制 | | blit\_sw\_CC | 如果是 True，則表示加速軟件驅動的 Surface 對象 colorkey 繪制 | | blit\_sw\_A | 如果是 True，則表示加速軟件驅動的Surface 對象 pixel alpha 繪制 | | current\_w, current\_h | 1\. 表示當前顯示模式的寬和高（如果在 display.set\_mode() 前被調用，則表示當前桌面的寬和高） 2. current\_w, current\_h 在 Pygame 1.8.0 以后，SDL 1.2.10 以后才支持 3. -1 表示錯誤，或者 SDL 版本太舊 | ### **pygame.display.get\_wm\_info()** 獲取關于當前窗口系統的信息。 get\_wm\_info() -> dict 創建一個由操作系統填充數據的字典。一些操作系統可能不會往里邊填充信息，則返回一個空字典。大多數平臺將返回一個 “window” 鍵，對應的值是當前顯示界面的系統 ID。 Pygame 1.7.1 新增加的。 ### **pygame.display.list\_modes()** 獲取全屏模式下可使用的分辨率。 list\_modes(depth=0, flags=pygame.FULLSCREEN) -> list 這個函數返回一個列表，包含指定顏色深度所支持的所有分辨率。如果顯示模式非全屏，則返回一個空列表。如果返回 -1 表示支持任何分辨率（類似于窗口模式）。返回的列表由大到小排列。 如果顏色深度是 0，SDL 將選擇當前/最合適的顏色深度顯示。flags 參數默認值是 pygame.FULLSCREEN，但你可能需要添加額外的全屏模式標志。 ### **pygame.display.mode\_ok()** 為顯示模式選擇最合適的顏色深度。 mode\_ok(size, flags=0, depth=0) -> depth 這個函數使用與 pygame.display.set\_mode() 函數一樣的參數。一般用于判斷一個顯示模式是否可用。如果顯示模式無法設置，則返回 0。正常情況下將會返回顯示需求的像素深度。 通常不用理會 depth 參數，除非一些支持多個顯示深度的平臺，它會提示哪個顏色深度是更合適的。 最有用的 flags 參數是 pygame.HWSURFACE，pygame.DOUBLEBUF 和 pygame.FULLSCREEN。如果這些標志不支持，那么該函數會返回 0。 ### **pygame.display.gl\_get\_attribute()** 獲取當前顯示界面 OpenGL 的屬性值。 gl\_get\_attribute(flag) -> value 在調用設置了 pygame.OPENGL 標志的 pygame.display.set\_mode() 函數之后，檢查 OpenGL 的屬性值不失為一個好的習慣。參考 pygame.display.gl\_set\_attribute() 關于合法標志的列表。 ### **pygame.display.gl\_set\_attribute()** 設置當前顯示模式的 OpenGL 屬性值。 gl\_set\_attribute(flag, value) -> None 當調用設置了 pygame.OPENGL 標志的 pygame.display.set\_mode() 函數時，Pygame 會自動設置 OpenGL 的一些屬性值，例如顏色和雙緩沖區。OpenGL 其實還提供了其他一些屬性值供你控制。在 flag 參數中傳入屬性名，并將其值設置在 value 參數中。這個函數必須在 pygame.display.set\_mode() 前設置。 這些 OPENGL 標志是： > GL\_ALPHA\_SIZE, GL\_DEPTH\_SIZE, GL\_STENCIL\_SIZE, GL\_ACCUM\_RED\_SIZE, GL\_ACCUM\_GREEN\_SIZE, GL\_ACCUM\_BLUE\_SIZE, GL\_ACCUM\_ALPHA\_SIZE, GL\_MULTISAMPLEBUFFERS, GL\_MULTISAMPLESAMPLES, GL\_STEREO ### **pygame.display.get\_active()** 當前顯示界面顯示在屏幕上時返回 True。 get\_active() -> bool pygame.display.set\_mode() 函數被調用之后，Surface 對象將被顯示在屏幕上。大多數窗口都支持隱藏，如果顯示的 Surface 對象被隱藏和最小化，那么該函數將返回 False。 ### **pygame.display.iconify()** 最小化顯示的 Surface 對象。 iconify() -> bool 將顯示的Surface 對象最小化或隱藏。并不是所有的操作系統都支持最小化顯示界面。如果該函數調用成功，返回 True。 當顯示界面最小化時，pygame.display.get\_active() 返回 False。事件隊列將接收到 ACTIVEEVENT 事件。 ### **pygame.display.toggle\_fullscreen()** 切換全屏模式和窗口模式。 toggle\_fullscreen() -> bool 切換全屏模式和窗口模式。這個函數只在 unix x11 顯示驅動下工作。在大多數情況下，建議調用 pygame.display.set\_mode() 創建一個新的顯示模式進行切換。 ### **pygame.display.set\_gamma()** 修改硬件顯示的 gama 坡道。 set\_gamma(red, green=None, blue=None) -> bool 設置硬件驅動顯示的紅色、綠色和藍色伽馬值。如果沒有傳遞 green 和 blue 參數，它們將與 red 值相等。不是所有的操作系統和硬件都支持伽馬坡道。如果函數修改成功，則返回 True。 伽馬值為 1.0 創建一個線性顏色表，較低的值會使屏幕變暗，較高的值會使屏幕變量。 ### **pygame.display.set\_gamma\_ramp()** 自定義修改硬件顯示的 gama 坡道 set\_gamma\_ramp(red, green, blue) -> bool 使用自定義表設置硬件驅動顯示的紅色、綠色和藍色伽馬坡道。每個參數必須是 256 位整數的列表。每位整數應該在 0 和 0xffff 之間。不是所有的操作系統和硬件都支持伽馬坡道。如果函數修改成功，則返回 True。 ### **pygame.display.set\_icon()** 修改顯示窗口的圖標。 set\_icon(Surface) -> None 設置顯示窗口執行時的圖標。所有的操作系統默認都是以簡單的 Pygame LOGO 作為圖標。 你可以傳入任何 Surface 對象作為圖標，但大多數操作系統要求圖標的大小是 32 \* 32。圖標可以設置 colorkey 透明度。 一些操作系統不允許修改顯示中的窗口圖標。對于這類操作系統，該函數需要再調用 pygame.display.set\_mode() 前先創建并設置圖標。 ### **pygame.display.set\_caption()** 設置當前窗口的標題欄。 set\_caption(title, icontitle=None) -> None 如果顯示窗口擁有一個標題欄，這個函數將修改窗口標題欄的文本。一些操作系統支持最小化窗口時切換標題欄，通過設置 icontitle 參數實現。 ### **pygame.display.get\_caption()** 獲取當前窗口的標題欄。 get\_caption() -> (title, icontitle) 返回當前窗口的標題欄和最小化標題欄，通常這兩個值是一樣的。 ### **pygame.display.set\_palette()** 設置顯示界面的調色板。 set\_palette(palette=None) -> None 這個函數將修改顯示界面的 8 位調色板。這不會改變Surface 對象實際的調色板，僅用于 Surface 對象的顯示。如果沒有傳入參數，將恢復系統默認調色板。調色板是一組 RGB 三元組序列。