glCopyPixels 函式

發行項
06/13/2023

glCopyPixels 函式會複製 framebuffer 中的圖元。

語法

void WINAPI glCopyPixels(
   GLint   x,
   GLint   y,
   GLsizei width,
   GLsizei height,
   GLenum  type
);

參數

x

要複製之圖元矩形區域左下角的視窗 X 平面座標。

y

要複製之圖元矩形區域左下角的視窗 Y 平面座標。

寬度

要複製之圖元矩形區域的寬度維度。不可為負值。

height (高度)

要複製之圖元矩形區域的高度維度。不可為負值。

type

指定 glCopyPixels 是要複製色彩值、深度值或樣板值。可接受的符號常數為。

值	意義
GL_COLOR	glCopyPixels函式會從目前指定為讀取來源緩衝區的緩衝區讀取索引或 RGBA 色彩， (請參閱glReadBuffer) 。如果 OpenGL 處於色彩索引模式：從這個緩衝區讀取的每個索引都會轉換成固定點格式，其中二進位點右邊有未指定的位數。每個索引都會由GL_INDEX_SHIFT位移開，並新增至GL_INDEX_OFFSET。如果GL_INDEX_SHIFT為負數，則班次會向右。在這兩種情況下，零位會填入結果中未指定的位位置。如果GL_MAP_COLOR為 true，索引會以查閱表格中參考的值取代GL_PIXEL_MAP_I_TO_I。不論索引的查閱取代是否完成，索引的整數部分會接著以 2^b 1 表示，其中b是色彩索引緩衝區中的位數。如果 OpenGL 處於 RGBA 模式：讀取之每個圖元的紅色、綠色、藍色和 Alpha 元件會轉換成具有未指定精確度的內部浮點格式。轉換會將最大可表示的元件值對應至 1.0，而元件值零會對應至 0.0。產生的浮點色彩值接著乘以GL_c_SCALE，並新增至GL_c_BIAS，其中 c 是紅色、綠色、藍色，以及個別色彩元件的 ALPHA。結果會限制在範圍 [0，1]。如果GL_MAP_COLOR為 true，則每個色彩元件會依查閱表格的大小來調整GL_PIXEL_MAP_c_TO_c，然後由該資料表中參考的值取代; c 分別是 R、G、B 或 A。產生的索引或 RGBA 色彩接著會藉由將目前的點陣位置z座標和紋理座標附加至每個圖元，然後將視窗 (座標指派給x_r + i、y_r + j) ，其中 (x_r 、y_r ) 是目前點陣位置，而圖元是j資料列中i位置的圖元。然後，這些圖元片段會像點陣化點、線條或多邊形所產生的片段一樣來處理。在片段寫入框架緩衝區之前，會套用紋理對應、模糊和所有片段作業。
GL_DEPTH	深度值是從深度緩衝區讀取，並直接轉換成具有未指定精確度的內部浮點格式。產生的浮點深度值接著乘以GL_DEPTH_SCALE，並新增至GL_DEPTH_BIAS。結果會限制在範圍 [0，1]。接著，產生的深度元件會藉由將目前點陣位置色彩或色彩索引和紋理座標附加至每個圖元，然後將視窗 (座標指派給x_r + i、y_r + j) ，其中 (x_r 、y_r ) 是目前的點陣位置，而圖元是j資料列中i位置的圖元。然後，這些圖元片段會像點陣化點、線條或多邊形所產生的片段一樣來處理。在片段寫入框架緩衝區之前，會套用紋理對應、模糊和所有片段作業。
GL_STENCIL	樣板索引是從樣板緩衝區讀取，並轉換成內部固定點格式，且二進位點右邊沒有指定的位數。然後，每個固定點索引會由GL_INDEX_SHIFT位移開，並新增至GL_INDEX_OFFSET。如果GL_INDEX_SHIFT為負數，則班次會向右。在這兩種情況下，零位會填入結果中未指定的位位置。如果GL_MAP_STENCIL為 true，索引會以查閱表格中參考的值取代GL_PIXEL_MAP_S_TO_S。不論索引的查閱取代是否完成，索引的整數部分就會是 AND2^b - 1，其中 b 是樣板緩衝區中的位數。產生的樣板索引接著會寫入樣板緩衝區，讓從 j資料列的 i位置讀取的索引會寫入x_r + i、 y_r + j) (的位置，其中 (x_r 、y_r ) 是目前的點陣位置。只有圖元擁有權測試、剪刀測試，以及樣板寫入遮罩會影響這些寫入。

值

意義

GL_COLOR

glCopyPixels函式會從目前指定為讀取來源緩衝區的緩衝區讀取索引或 RGBA 色彩， (請參閱glReadBuffer) 。
如果 OpenGL 處於色彩索引模式：

從這個緩衝區讀取的每個索引都會轉換成固定點格式，其中二進位點右邊有未指定的位數。
每個索引都會由GL_INDEX_SHIFT位移開，並新增至GL_INDEX_OFFSET。如果GL_INDEX_SHIFT為負數，則班次會向右。在這兩種情況下，零位會填入結果中未指定的位位置。
如果GL_MAP_COLOR為 true，索引會以查閱表格中參考的值取代GL_PIXEL_MAP_I_TO_I。
不論索引的查閱取代是否完成，索引的整數部分會接著以 2^b 1 表示，其中b是色彩索引緩衝區中的位數。

如果 OpenGL 處於 RGBA 模式：

讀取之每個圖元的紅色、綠色、藍色和 Alpha 元件會轉換成具有未指定精確度的內部浮點格式。
轉換會將最大可表示的元件值對應至 1.0，而元件值零會對應至 0.0。
產生的浮點色彩值接著乘以GL_c_SCALE，並新增至GL_c_BIAS，其中 c 是紅色、綠色、藍色，以及個別色彩元件的 ALPHA。
結果會限制在範圍 [0，1]。
如果GL_MAP_COLOR為 true，則每個色彩元件會依查閱表格的大小來調整GL_PIXEL_MAP_c_TO_c，然後由該資料表中參考的值取代; c 分別是 R、G、B 或 A。產生的索引或 RGBA 色彩接著會藉由將目前的點陣位置z座標和紋理座標附加至每個圖元，然後將視窗 (座標指派給x_r + i、y_r + j) ，其中 (x_r 、y_r ) 是目前點陣位置，而圖元是j資料列中i位置的圖元。然後，這些圖元片段會像點陣化點、線條或多邊形所產生的片段一樣來處理。在片段寫入框架緩衝區之前，會套用紋理對應、模糊和所有片段作業。

GL_DEPTH

深度值是從深度緩衝區讀取，並直接轉換成具有未指定精確度的內部浮點格式。產生的浮點深度值接著乘以GL_DEPTH_SCALE，並新增至GL_DEPTH_BIAS。結果會限制在範圍 [0，1]。
接著，產生的深度元件會藉由將目前點陣位置色彩或色彩索引和紋理座標附加至每個圖元，然後將視窗 (座標指派給x_r + i、y_r + j) ，其中 (x_r 、y_r ) 是目前的點陣位置，而圖元是j資料列中i位置的圖元。然後，這些圖元片段會像點陣化點、線條或多邊形所產生的片段一樣來處理。在片段寫入框架緩衝區之前，會套用紋理對應、模糊和所有片段作業。

GL_STENCIL

樣板索引是從樣板緩衝區讀取，並轉換成內部固定點格式，且二進位點右邊沒有指定的位數。然後，每個固定點索引會由GL_INDEX_SHIFT位移開，並新增至GL_INDEX_OFFSET。如果GL_INDEX_SHIFT為負數，則班次會向右。在這兩種情況下，零位會填入結果中未指定的位位置。如果GL_MAP_STENCIL為 true，索引會以查閱表格中參考的值取代GL_PIXEL_MAP_S_TO_S。不論索引的查閱取代是否完成，索引的整數部分就會是 AND2^b - 1，其中 b 是樣板緩衝區中的位數。產生的樣板索引接著會寫入樣板緩衝區，讓從 j資料列的 i位置讀取的索引會寫入x_r + i、 y_r + j) (的位置，其中 (x_r 、y_r ) 是目前的點陣位置。只有圖元擁有權測試、剪刀測試，以及樣板寫入遮罩會影響這些寫入。

傳回值

此函式不會傳回值。

錯誤碼

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

名稱	意義
GL_INVALID_ENUM	類型不是接受的值。
GL_INVALID_VALUE	寬度或高度為負數。
GL_INVALID_OPERATION	類型 GL_DEPTH，而且沒有深度緩衝區。
GL_INVALID_OPERATION	類型 GL_STENCIL，而且沒有樣板緩衝區。
GL_INVALID_OPERATION	在對 glBegin 的呼叫與 glEnd的對應呼叫之間呼叫函式。

備註

glCopyPixels函式會將圖元的螢幕對齊矩形從指定的框架緩衝區位置複製到相對於目前點陣位置的區域。只有在整個圖元來源區域位於視窗的公開部分時，才會妥善定義其作業。從視窗外部，或從未公開之視窗的區域，複本的結果與硬體相依且未定義。

x和y參數會指定要複製之矩形區域左下角的視窗座標。寬度和高度參數會指定要複製之矩形區域的維度。寬度和高度都必須是非負值。

數個參數控制複製圖元資料時的處理。這些參數是使用三個函式來設定：glPixelTransfer、glPixelMap 和 glPixelZoom。本主題描述這三個函式所指定參數的 glCopyPixels 效果，但並非所有參數。

glCopyPixels 函式會從每個圖元複製值，並將左下角 (x i + ， y + j) 0 = i<width，0 = j<height。此圖元稱為j列中的i圖元。圖元會依資料列順序從最低複製到最高資料列，在每個資料列中由左至右。

類型參數會指定要複製色彩、深度或樣板資料。

到目前為止所述的點陣化假設圖元縮放比例為 1.0。如果您使用 glPixelZoom 來變更 x 和 y 圖元縮放因數，圖元會轉換成片段，如下所示。如果 (x_r 、y_r ) 是目前的點陣位置，而指定的圖元位於來源圖元矩形的j列中，則會針對中心位於矩形中且位於角落的圖元產生片段

(x_r + zoom？ i， y_r + zoom_yj)

及

(x_r + 縮放嗎？ (i + 1) ，y_r + 縮放_y (j + 1) )

在哪裡縮放？是 GL_ZOOM_X 的值，縮放_y 是 GL_ZOOM_Y 的值。

glPixelStore指定的模式不會影響glCopyPixels的作業。

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

glGet 與引數GL_CURRENT_RASTER_POSITION

具有引數的glGet GL_CURRENT_RASTER_POSITION_VALID

若要將視窗左下角的色彩圖元複製到目前的點陣位置，請使用

glCopyPixels ( 0， 0， 1， 1， GL_COLOR ) ;

規格需求

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

另請參閱

glBegin
glDepthFunc
glDrawBuffer
glDrawPixels
glEnd
glGet
glPixelMap
glPixelStore
glPixelTransfer
glPixelZoom
glRasterPos
glReadBuffer
glReadPixels
glStencilFunc

共用方式為

glCopyPixels 函式

語法

參數

傳回值

錯誤碼

備註

規格需求

另請參閱

意見反應

其他資源