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函式可以擷取下列錯誤碼。
| 名稱 | 意義 |
|---|---|
|
格式 或 類型 不是接受的值。 |
|
寬度或高度為負數。 |
|
format 是GL_COLOR_INDEX，而色彩緩衝區會儲存 RGBA 或 BGRA 色彩元件。 |
|
格式 GL_STENCIL_INDEX，而且沒有樣板緩衝區。 |
|
格式 GL_DEPTH_COMPONENT，而且沒有深度緩衝區。 |
|
在 對 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 [僅限傳統型應用程式] |
| 標頭 |
|
| 程式庫 |
|
| DLL |
|