glReadPixels 函式

  • 發行項

glReadPixels 函式會從 framebuffer 讀取圖元區塊。

語法

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

參數

x

從框架緩衝區讀取之第一個圖元的視窗 x 座標。 與 y 座標一起，指定矩形像素區塊左下角的位置。

y

從框架緩衝區讀取之第一個圖元的視窗 Y 座標。 與 x 座標一起指定矩形像素區塊左下角的位置。

寬度

圖元矩形的寬度。

height (高度)

圖元矩形的高度。 值 「1」 的寬度和高度參數對應至單一圖元。

format

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

值 意義
GL_COLOR_INDEX
 色彩索引是從 glReadBuffer所選取的色彩緩衝區讀取。 每個索引會根據GL_INDEX_SHIFT的值和符號，轉換成固定點、向左或向右移位，並新增至GL_INDEX_OFFSET。 如果GL_MAP_COLOR GL_TRUE，索引會由資料表中的對應取代GL_PIXEL_MAP_I_TO_I。
GL_STENCIL_INDEX
 樣板值是從樣板緩衝區讀取。 每個索引會根據GL_INDEX_SHIFT的值和符號，轉換成固定點、向左或向右移位，並新增至GL_INDEX_OFFSET。 如果GL_MAP_STENCIL GL_TRUE，索引會由資料表中的對應取代GL_PIXEL_MAP_S_TO_S。
GL_DEPTH_COMPONENT
 深度值是從深度緩衝區讀取。 每個元件都會轉換成浮點，讓最小深度值對應至 0.0，而最大值會對應至 1.0。 然後，每個元件會乘以GL_DEPTH_SCALE、新增至GL_DEPTH_BIAS，最後固定至範圍 [0，1]。
GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA、GL_RGB、GL_RGBA、GL_BGR_EXT、GL_BGRA_EXT、GL_LUMINANCE GL_LUMINANCE_ALPHA
 視色彩緩衝區儲存色彩索引或 RGBA 色彩元件而定，處理會有所不同。 如果儲存色彩索引，則會從 glReadBuffer所選取的色彩緩衝區讀取它們。 每個索引會根據GL_INDEX_SHIFT的值和符號，轉換成固定點、向左或向右移位，並新增至GL_INDEX_OFFSET。 索引接著會由紅色、綠色、藍色和 Alpha 值取代，方法是編制索引GL_PIXEL_MAP_I_TO_R、GL_PIXEL_MAP_I_TO_G、GL_PIXEL_MAP_I_TO_B和GL_PIXEL_MAP_I_TO_A資料表。 如果 RGBA 色彩元件儲存在色彩緩衝區中，則會從 glReadBuffer所選取的色彩緩衝區讀取它們。 每個色彩元件都會轉換成浮點，讓零濃度對應至 0.0，而完整濃度會對應至 1.0。 然後，每個元件會乘以GL_c_SCALE並新增至GL_c_BIAS，其中 c 是GL_RED、GL_GREEN、GL_BLUE和GL_ALPHA。 每個元件都會固定在範圍 [0，1]。 最後，如果GL_MAP_COLOR GL_TRUE，則每個色彩元件 c 都會由資料表GL_PIXEL_MAP_c_TO_c中的對應取代，其中 c 會再次GL_RED、GL_GREEN、GL_BLUE和GL_ALPHA。 執行查閱之前，每個元件都會調整為其對應資料表的大小。 最後，會捨棄不必要的資料。 例如，GL_RED捨棄綠色、藍色和 Alpha 元件，而GL_RGB只會捨棄 Alpha 元件。 GL_LUMINANCE會將單一元件值計算為紅色、綠色和藍色元件的總和，而GL_LUMINANCE_ALPHA會執行相同的動作，同時將 Alpha 保留為第二個值。

type

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

類型 索引遮罩 元件轉換
GL_UNSIGNED_BYTE 281 (281) c
GL_BYTE 271 [ (271) c-1]/2
GL_BITMAP 1 1
GL_UNSIGNED_SHORT 2 61 (2 61) c
GL_SHORT 2 51 [ (2 51) c1]/2
GL_UNSIGNED_INT_ 2 1 (2 1) c
GL_INT 2 1 [ (2 1) c1]/2
GL_FLOAT 無 c

圖元

傳回圖元資料。

傳回值

此函式不會傳回值。

錯誤碼

glGetError函式可以擷取下列錯誤碼。

名稱 意義
GL_INVALID_ENUM
 格式 或 類型 不是接受的值。
GL_INVALID_VALUE
 寬度或高度為負數。
GL_INVALID_OPERATION
 format 是GL_COLOR_INDEX，而色彩緩衝區會儲存 RGBA 或 BGRA 色彩元件。
GL_INVALID_OPERATION
 格式 GL_STENCIL_INDEX，而且沒有樣板緩衝區。
GL_INVALID_OPERATION
 格式 GL_DEPTH_COMPONENT，而且沒有深度緩衝區。
GL_INVALID_OPERATION
 在 對 glBegin 的呼叫與 glEnd的對應呼叫之間呼叫函式。

備註

glReadPixels函式會從框架緩衝區傳回圖元資料，從左下角位於位置 (x、y) 的圖元開始，傳回從位置圖元開始的用戶端記憶體。 數個參數會控制圖元資料的處理，然後再放入用戶端記憶體中。 這些參數是使用三個命令來設定： glPixelStore、 glPixelTransfer和 glPixelMap。 本主題描述大部分 glReadPixels 的效果，但不是這三個命令所指定的所有參數。

glReadPixels 函式會從左下角 (x + i、y + j) 0 = i <寬度和 0 = j <高度的每個圖元傳回值。 此圖元稱為第 j列中的第i個圖元。 圖元會依資料列順序從最低到最高資料列傳回，每個資料列由左至右。

上述的移位、刻度、偏差和查閱因素全都由 glPixelTransfer指定。 查閱表格內容是由 glPixelMap所指定。

最後一個步驟牽涉到將索引或元件轉換成適當的格式，如 類型所指定。 如果 格式 是GL_COLOR_INDEX或GL_STENCIL_INDEX， 且類型 不是GL_FLOAT，則每個索引都會以下表中提供的遮罩值遮罩。 如果 類型 是GL_FLOAT，則每個整數索引都會轉換成單精確度浮點格式。

如果 格式 是GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA、GL_RGB、GL_RGBA、GL_BGR_EXT、GL_BGRA_EXT、GL_LUMINANCE或 GL_LUMINANCE_ALPHA，則 不會GL_FLOAT，則每個元件都會乘以上表中所示的乘數。 如果類型GL_FLOAT，則如果每個元件與 OpenGL) 所使用的浮點格式不同，則會依原狀傳遞 (或轉換成用戶端的單精確度浮點格式。

傳回值會放在記憶體中，如下所示。 如果格式是GL_COLOR_INDEX、GL_STENCIL_INDEX、GL_DEPTH_COMPONENT、GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA或GL_LUMINANCE，則會傳回單一值，並將j列中第i個圖元的資料放在j (j ) width + i的位置。 GL_RGB和GL_BGR_EXT傳回三個值，GL_RGBA和GL_BGRA_EXT傳回四個值，而GL_LUMINANCE_ALPHA傳回每個圖元的兩個值，且所有值都對應至佔用連續空間的單一 圖元圖元。 glPixelStore所設定的儲存體參數，例如GL_PACK_SWAP_BYTES和GL_PACK_LSB_FIRST，會影響將資料寫入記憶體的方式。 如需描述，請參閱 glPixelStore 。

位於連接到目前 OpenGL 內容之視窗外的圖元值是未定義的。

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

下列函式會擷取 與 glReadPixels相關的資訊：

glGet 與引數GL_INDEX_MODE

規格需求

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

另請參閱

glBegin

glCopyPixels

glDrawPixels

glEnd

glPixelMap

glPixelStore

glPixelTransfer

glReadBuffer