glReadPixels 函式

GlReadPixels 函式會從畫面格緩衝區讀取圖元區塊。

語法

void WINAPI glReadPixels(
   GLint   x,
   GLint   y,
   GLsizei width,
   GLsizei height,
   GLenum  format,
   GLenum  type,
   GLvoid  *pixels
);

參數

x

從畫面格緩衝區讀取之第一個圖元的視窗 x 座標。 使用 y 座標,指定圖元矩形區塊的左下角位置。

y

從畫面格緩衝區讀取之第一個圖元的視窗 y 座標。 搭配 x 座標,指定圖元矩形區塊的左下角位置。

width (寬度)

圖元矩形的寬度。

height (高度)

圖元矩形的高度。 值為 "1" 的 寬度高度 參數對應到單一圖元。

format

圖元資料的格式。 接受下列符號值:

意義
GL _ 色彩 _ 索引
色彩索引是從 glReadBuffer選取的色彩緩衝區中讀取。 每個索引都會轉換成固定點、向左或向右移動,取決於 GL 索引移位的值和正負號 _ _ ,並新增至 gl _ 索引 _ 位移。 如果 GL _ 地圖 _ 色彩為 gl _ TRUE,則會將索引取代為數據表 GL _ 圖元 _ 地圖 _ i _ 到 _ i 中的對應。
GL _ 樣板 _ 索引
樣板值會從樣板緩衝區中讀取。 每個索引都會轉換成固定點、向左或向右移動,取決於 GL 索引移位的值和正負號 _ _ ,並新增至 gl _ 索引 _ 位移。 如果 GL _ 地圖樣板 _ 為 gl _ ,則會將索引取代為數據表 GL _ 圖元 _ 地圖 _ s _ 到 _ s 中的對應。
GL _ 深度 _ 元件
深度值是從深度緩衝區讀取的。 每個元件都會轉換成浮點數,因此最小深度值會對應至0.0,而最大值會對應至1.0。 然後,每個元件會乘以 GL _ 深度 _ 比例、新增至 GL _ 深度 _ 偏差,最後壓制至範圍 [ 0,1 ] 。
GL _ RED、GL _ 綠、GL _ BLUE、GL _ ALPHA、GL _ RGB、GL _ RGBA、GL _ BGR _ EXT、GL _ BGRA _ EXT、GL _ 亮度、GL _ 亮度 _ ALPHA
處理會因色彩緩衝區儲存色彩索引或 RGBA 色彩元件而有所不同。 如果已儲存色彩索引,則會從 glReadBuffer所選取的色彩緩衝區讀取這些索引。 每個索引都會轉換成固定點、向左或向右移動,取決於 GL 索引移位的值和正負號 _ _ ,並新增至 gl _ 索引 _ 位移。 然後,索引會由將 GL _ 圖元 _ 地圖 _ i _ 到 _ R、gl _ 圖元 _ 地圖 _ i _ 到 _ G、gl _ 圖元 _ 地圖 i _ _ 到 _ B,以及 gl _ 圖元 _ 對應 _ i _ 到 _ 資料表的紅色、綠色、藍色和 Alpha 值取代。 如果 RGBA 色彩元件儲存在色彩緩衝區中,則會從 glReadBuffer 所選取的色彩緩衝區讀取它們。 每個色彩元件都會轉換成浮點數,如此一來,就會將零濃度對應到0.0,並將完整強度對應到1.0。 接著,每個元件會乘以 GL _ c _ 規模並新增至 gl _ c _ 偏差,其中 c 是 gl _ RED、gl 綠、 _ gl _ BLUE 和 gl _ ALPHA。 每個元件都會壓制至範圍 [ 0、1 ] 。 最後,如果 GL _ 對應 _ 色彩為 gl _ TRUE,則每個色彩元件 c 都會取代為數據表 GL _ 圖元 _ 地圖 _ c 到 c 中的對應 _ _ ,其中 c 再次為 gl _ RED、gl _ 綠、gl _ 藍色和 gl _ ALPHA。 在執行查閱之前,每個元件都會調整為其對應資料表的大小。 最後,會捨棄不必要的資料。 例如,GL _ RED 會捨棄綠色、藍色和 Alpha 元件,而 gl RGB 則 _ 只捨棄 Alpha 元件。 GL _ 亮度會將單一元件值計算為紅色、綠色和藍色元件的總和,而 gl _ 亮度 _ ALPHA 會執行相同的工作,同時將 ALPHA 保持為第二個值。

type

圖元資料的資料類型。 必須是下列其中一個值。

類型 索引遮罩 元件轉換
GL 不 _ 帶正負號的 _ 位元組 281 (281) c
GL _ 位元組 271 [ (271) c-1 ] /2
GL _ 點陣圖 1 1
GL 不 _ 帶正負號 _ 簡短 2 61 (2 61) c
GL _ 短期 2 51 [ (2 51) c 1 ] /2
GL 不 _ 帶正負號 _ INT_ 2 1 (2 1) c
GL _ INT 2 1 [ (2 1) c 1 ] /2
GL _ FLOAT c

圖元

傳回圖元資料。

傳回值

此函式不會傳回值。

錯誤碼

GlGetError函式可以取出下列錯誤碼。

Name 意義
GL _ 無效 _ 列舉
格式類型 不是可接受的值。
GL _ 無效 _ 值
寬度高度 都是負數。
GL _ 不正確 _ 操作
格式 為 GL _ 色彩 _ 索引,以及儲存 RGBA 或 BGRA 色彩元件的色彩緩衝區。
GL _ 不正確 _ 操作
格式 為 GL 樣板索引,但沒有樣板 _ _ 緩衝區。
GL _ 不正確 _ 操作
格式 為 GL _ 深度 _ 元件,但沒有深度緩衝區。
GL _ 不正確 _ 操作
呼叫 glBegin 和對應的 glEnd呼叫之間呼叫了函數。

備註

GlReadPixels 函式會從畫面格緩衝區傳回圖元資料,從左下角位置 (xy) 的圖元開始,到以位置 圖元 開始的用戶端記憶體。 有幾個參數會控制將圖元資料放入用戶端記憶體之前的處理。 這些參數會以三個命令設定: glPixelStoreglPixelTransferglPixelMap。 本主題說明大部分(但不是這三個命令所指定的所有參數)對 glReadPixels 的影響。

GlReadPixels 函式會從左下角 (x + i、 y + j) 的每個圖元傳回值,0 = i <寬度 和 0 = j <高度。 這個圖元就是第一個 j# 資料列中的第 i 個圖元。 在每個資料列中,從最小到最高的資料列,以左至右的順序傳回圖元。

上述的 shift、scale、偏差和 lookup 因數都是由 glPixelTransfer所指定。 查閱資料表內容是由 glPixelMap所指定。

最後一個步驟牽涉到將索引或元件轉換成正確的格式,如 類型 所指定。 如果 格式 為 gl _ 色彩 _ 索引或 gl _ 樣板 _ 索引,且 類型 不是 gl _ FLOAT,則會使用下表中提供的遮罩值來遮罩每個索引。 如果 type 是 GL _ FLOAT,則每個整數索引都會轉換成單精確度浮點數格式。

如果 格式 為 gl _ RED、GL _ 綠、gl _ BLUE、gl _ ALPHA、GL _ RGB、GL _ RGBA、GL _ BGR _ EXT、gl _ BGRA _ EXT、gl _ 亮度或 gl _ 亮度 _ ALPHA,而 類型 不是 gl _ FLOAT,則每個元件都會乘以上表所示的乘數。 如果 type 是 GL _ FLOAT,則會將每個元件當做 (傳遞,或轉換成用戶端的單精確度浮點數格式(如果不同于 OpenGL) 所使用的格式)。

傳回值會放在記憶體中,如下所示。 如果 格式 為 gl _ 色彩 _ 索引、gl _ 樣板 _ 索引、gl _ 深度 _ 元件、gl _ 紅色、gl _ 綠色、gl _ 藍色、gl _ ALPHA 或 gl _ 亮度,則會傳回單一值,而 j# 第一個資料列的第 i 圖元資料會放在位置 (j ) 寬度 + i。 GL _ RGB 和 gl _ BGR _ ext 會傳回三個值、GL _ RGBA 和 gl BGRA EXT 會傳回四個值 _ _ ,而 gl _ 亮度 ALPHA 會 _ 針對每個圖元傳回兩個值,並將所有值對應至佔用連續空間的單一圖元(以 圖元為單位)GlPixelStore所設定的儲存體參數(例如 GL _ 套件 _ 交換 _ 位元組和 gl _ 套件 _ LSB _ )會先影響資料寫入記憶體的方式。 如需描述,請參閱 glPixelStore

在連接到目前 OpenGL 內容的視窗外的圖元值未定義。

如果產生錯誤,則不會對 圖元 的內容進行任何變更。

下列函式會抓取 glReadPixels 的相關資訊:

具有引數 GL _ 索引 _ 模式的 glGet

規格需求

需求
最低支援的用戶端
Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器
Windows 2000 Server [僅限傳統型應用程式]
標頭
Gl
程式庫
Opengl32 .lib
DLL
Opengl32.dll

另請參閱

glBegin

glCopyPixels

glDrawPixels

glEnd

glPixelMap

glPixelStore

glPixelTransfer

glReadBuffer