glDrawPixels 函式

glDrawPixels函式會將圖元區塊寫入框架緩衝區。

語法

void WINAPI glDrawPixels(
         GLsizei width,
         GLsizei height,
         GLenum  format,
         GLenum  type,
   const GLvoid  *pixels
);

參數

寬度

要寫入框架緩衝區之圖元矩形的寬度維度。

height (高度)

要寫入框架緩衝區之圖元矩形的高度維度。

format

圖元資料的格式。 可接受的符號常數如下所示。

意義
GL_COLOR_INDEX
每個圖元都是單一值,也就是色彩索引。
  1. glDrawPixels函式會將每個圖元轉換成固定點格式,不論記憶體資料類型為何,二進位點右邊都有未指定的位數。 浮點值會轉換成真正的固定點值。 glDrawPixels函式會將帶正負號和不帶正負號的整數資料轉換成零。 函式會將點陣圖資料轉換成 0.0 或 1.0。
  2. glDrawPixels函式會將每個固定點索引移GL_INDEX_SHIFT位,並將它新增至GL_INDEX_OFFSET。 如果GL_INDEX_SHIFT為負數,則移位會向右。 不論是哪一種情況,零位會填滿結果中未指定的位位置。
  3. 在 RGBA 模式中, glDrawPixels 會使用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 圖元。 當在色彩索引模式中且GL_MAP_COLOR為 true 時,會將索引取代為查閱表格中 glDrawPixels 參考的值GL_PIXEL_MAP_I_TO_I。
  4. 不論索引的查閱取代是否完成,索引的整數部分都是 AND2b - 1,其中 b 是色彩索引緩衝區中的位數。
  5. 產生的索引或 RGBA 色彩接著會藉由將目前的點陣位置z座標和紋理座標附加至每個圖元,然後將xy視窗座標指派給第 n個片段,以轉換成片段?」 = xr + n mod寬度
    y? = yr + n/width
    其中 (xryr ) 是目前的點陣位置。
  6. glDrawPixels 函式會將這些圖元片段視為點陣化點、線條或多邊形所產生的片段。 它會在將片段寫入框架緩衝區之前,先套用紋理對應、霧和所有片段作業。
GL_STENCIL_INDEX
每個圖元都是單一值,即樣板索引。
  1. glDrawPixels函式會將它轉換成固定點格式,不論記憶體資料類型為何,二進位點右邊有未指定的位數。 浮點值會轉換成真正的固定點值。 glDrawPixels函式會將帶正負號和不帶正負號的整數資料轉換成零。 點陣圖資料會轉換成 0.0 或 1.0。
  2. glDrawPixels函式會將每個固定點索引移GL_INDEX_SHIFT位,並將其新增至GL_INDEX_OFFSET。 如果GL_INDEX_SHIFT為負數,則移位會向右。 不論是哪一種情況,零位會填滿結果中未指定的位位置。
  3. 如果GL_MAP_STENCIL為 true,則會將索引取代為查閱表格中 glDrawPixels 參考的值GL_PIXEL_MAP_S_TO_S。
  4. 不論索引的查閱取代是否完成,索引的整數部分就會是 AND2b - 1,其中 b 是樣板緩衝區中的位數。 產生的樣板索引接著會寫入樣板緩衝區,讓 第 n個索引寫入位置 x? = xr + n mod寬度
    y? = yr + n/width
    其中 (xr yr ) 是目前的點陣位置。 只有圖元擁有權測試、剪刀測試,以及樣板寫入遮罩會影響這些寫入。
GL_DEPTH_COMPONENT
每個圖元都是單一深度元件。
  1. glDrawPixels函式會將浮點數據直接轉換成具有未指定精確度的內部浮點格式。 帶正負號的整數資料會以線性方式對應至內部浮點格式,使最正數可表示的整數值對應至 1.0,而最負數的可表示值則對應至 -1.0。 不帶正負號的整數資料對應方式類似:最大整數值對應至 1.0,而零對應至 0.0。
  2. glDrawPixels函式會將產生的浮點深度值乘以GL_DEPTH_SCALE,並將其新增至GL_DEPTH_BIAS。 結果會限制為範圍 [0,1]。
  3. glDrawPixels函式會將目前點陣位置色彩或色彩索引和紋理座標附加至每個圖元,然後將xy視窗座標指派給第 n個片段,以將產生的深度元件轉換成片段?」 = xr + n mod寬度
    y? = yr + n/width
    其中 ( xryr ) 是目前的點陣位置。
  4. 然後,這些圖元片段會被視為點陣化點、線條或多邊形所產生的片段。 glDrawPixels函式會在將片段寫入框架緩衝區之前,套用紋理對應、霧和所有片段作業。
GL_RGBA
每個圖元都是依此順序排列的四個元件群組:紅色、綠色、藍色、Alpha。
  1. glDrawPixels函式會將浮點值直接轉換成具有未指定精確度的內部浮點格式。 帶正負號的整數值會以線性方式對應到內部浮點格式,讓最正表示的整數值對應至 1.0,而最負數的可表示值會對應至 -1.0。 不帶正負號的整數資料對應方式類似:最大整數值對應至 1.0,而零對應至 0.0。
  2. glDrawPixels函式會將產生的浮點色彩值乘以GL_c_SCALE,並將其新增至GL_c_BIAS,其中c是個別色彩元件的 RED、GREEN、BLUE 和 ALPHA。 結果會限制為範圍 [0,1]。
  3. 如果GL_MAP_COLOR為 true, glDrawPixels 會依查閱表格的大小來調整每個色彩元件GL_PIXEL_MAP_c_TO_c,然後將元件取代為該資料表中所參考的值; c 分別是 R、G、B 或 A。
  4. glDrawPixels函式會將目前點陣位置z座標和紋理座標附加至每個圖元,然後將xy視窗座標指派給第 n個片段,以將產生的 RGBA 色彩轉換成片段?」 = xr + n mod寬度
    y? = yr + n /width
    其中 (xryr ) 是目前的點陣位置。
  5. 然後,這些圖元片段會被視為點陣化點、線條或多邊形所產生的片段。 glDrawPixels函式會在將片段寫入框架緩衝區之前,套用紋理對應、霧和所有片段作業。
GL_RED
每個圖元都是單一紅色元件。
glDrawPixels函式會以 RGBA 圖元紅色元件相同的方式,將此元件轉換成內部浮點格式,然後將它轉換成綠色和藍色設定為 0.0 的 RGBA 圖元,並將 Alpha 設定為 1.0。 轉換之後,會將圖元視為 RGBA 圖元。
GL_GREEN
每個圖元都是單一綠色元件。
glDrawPixels函式會以 RGBA 圖元綠色元件相同的方式,將此元件轉換成內部浮點格式,然後將它轉換成紅色和藍色設定為 0.0 的 RGBA 圖元,並將 Alpha 設定為 1.0。 轉換之後,會將圖元視為 RGBA 圖元。
GL_BLUE
每個圖元都是單一藍色元件。
glDrawPixels函式會以與 RGBA 圖元藍色元件相同的方式,將此元件轉換成內部浮點格式,然後將它轉換成紅色和綠色設定為 0.0 的 RGBA 圖元,並將 Alpha 設定為 1.0。 轉換之後,會將圖元視為 RGBA 圖元。
GL_ALPHA
每個圖元都是單一 Alpha 元件。
glDrawPixels函式會將此元件轉換成內部浮點格式,與 RGBA 圖元的 Alpha 元件相同,然後將它轉換成紅色、綠色和藍色設為 0.0 的 RGBA 圖元。 轉換之後,會將圖元視為 RGBA 圖元。
GL_RGB
每個圖元都是依此順序排列的三個元件群組:紅色、綠色、藍色。 glDrawPixels函式會將每個元件轉換成內部浮點格式,與 RGBA 圖元的紅色、綠色和藍色元件相同。 色彩三重會轉換成 RGBA 圖元,並將 Alpha 設為 1.0。 轉換之後,會將圖元視為 RGBA 圖元。
GL_LUMINANCE
每個圖元都是單一亮度元件。
glDrawPixels函式會以 RGBA 圖元的紅色元件相同方式,將此元件轉換為內部浮點格式,然後將它轉換成紅色、綠色和藍色設定為 1.0 的 RGBA 圖元。 轉換之後,會將圖元視為 RGBA 圖元。
GL_LUMINANCE_ALPHA
每個圖元都是依此順序排列的兩個元件群組:亮度、Alpha。
glDrawPixels函式會將這兩個元件轉換成內部浮點格式,與 RGBA 圖元的紅色元件相同,然後將它們轉換成紅色、綠色和藍色設定為轉換的 Alpha 值 RGBA 圖元。 轉換之後,會將圖元視為 RGBA 圖元。
GL_BGR_EXT
每個圖元都是依此順序排列的三個元件群組:藍色、綠色、紅色。
GL_BGR_EXT提供符合 Windows 裝置獨立點陣圖記憶體配置的格式, (DIB) 。 因此,您的應用程式可以搭配 Windows 函式呼叫和 OpenGL 圖元函式呼叫使用相同的資料。
GL_BGRA_EXT
每個圖元都是依此順序排列的四個元件群組:藍色、綠色、紅色、Alpha。
GL_BGRA_EXT提供符合 Windows 裝置獨立點陣圖記憶體配置的格式, (DIB) 。 因此,您的應用程式可以搭配 Windows 函式呼叫和 OpenGL 圖元函式呼叫使用相同的資料。

type

圖元的資料類型。 以下是可接受的符號常數及其意義。

意義
GL_UNSIGNED_BYTE
不帶正負號的 8 位元整數
GL_BYTE
帶正負號的 8 位元整數
GL_BITMAP
不帶正負號 8 位整數中的單一位
GL_UNSIGNED_SHORT
不帶正負號的 16 位元整數
GL_SHORT
帶正負號的 16 位元整數
GL_UNSIGNED_INT
不帶正負號的 32 位元整數
GL_INT
32 位元整數
GL_FLOAT
單精確度浮點數

圖元

圖元資料的指標。

傳回值

此函式不會傳回值。

錯誤碼

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

名稱 意義
GL_INVALID_VALUE
寬度高度為負數。
GL_INVALID_ENUM
格式類型不是接受的值。
GL_INVALID_OPERATION
format 是GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA、GL_RGB、GL_RGBA、GL_BGR_EXT、GL_BGRA_EXT、GL_LUMINANCE或GL_LUMINANCE_ALPHA,而 OpenGL 處於色彩索引模式。
GL_INVALID_ENUM
類型 GL_BITMAP, 且格式 不是GL_COLOR_INDEX或GL_STENCIL_INDEX。
GL_INVALID_OPERATION
format 已GL_STENCIL_INDEX,而且沒有樣板緩衝區。
GL_INVALID_OPERATION
函式是在 對 glBegin 的呼叫和 glEnd的對應呼叫之間呼叫。

備註

glDrawPixels 函式會從記憶體讀取圖元資料,並將它寫入到相對於目前點陣位置的框架緩衝區中。 使用 glRasterPos 來設定目前的點陣位置,並使用 glGet 搭配引數GL_CURRENT_RASTER_POSITION來查詢點陣位置。

數個參數會定義記憶體中的圖元資料編碼,並控制圖元資料的處理,再將其放在框架緩衝區中。 這些參數會設定為四個函式:glPixelStoreglPixelTransferglPixelMap 和 glPixelZoom 本主題描述這四個函式所指定之參數 的 glDrawPixels 效果,但並非全部。

資料會從 圖元 讀取為帶正負號或不帶正負號的位元組序列、帶正負號或不帶正負號的短數、帶正負號或不帶正負號的整數或單精確度浮點值,視 類型而定。 每個位元組、短數、整數或浮點值都會根據 格式解譯為一個色彩或深度元件,或一個索引。 索引一律會個別處理。 色彩元件會根據 格式,再次視為一、二、三或四個值的群組。 個別索引和元件群組稱為圖元。 如果 類型 為 GL_BITMAP,則資料必須是不帶正負號的位元組,而且 格式 必須是GL_COLOR_INDEX或GL_STENCIL_INDEX。 每個不帶正負號的位元組都會被視為 8 個 1 位圖元,而位順序是由 GL_UNPACK_LSB_FIRST (判斷,請參閱 glPixelStore) 。

高度圖元的寬度是從記憶體讀取,從位置圖元開始。 根據預設,這些圖元取自相鄰記憶體位置,不同之處在于讀取所有 寬度 圖元之後,讀取指標會進階到下一個 4 位元組界限。 glPixelStore函式會指定 4 位元組的資料列對齊方式與引數GL_UNPACK_ALIGNMENT,而且您可以將它設定為 1、2、4 或 8 個位元組。 其他圖元存放區參數會在讀取第一個圖元之前,以及在讀取所有 寬度 圖元之後指定不同的讀取指標進展。 glPixelStore函式會根據glPixelTransferglPixelMap所指定的數個參數值,以相同方式在記憶體中讀取的每個寬度高度圖元上運作。 這些作業的詳細資料,以及繪製圖元的目標緩衝區,都是以 格式指定的像素格式所特有。

到目前為止所述的點陣化假設圖元縮放因數為 1.0。 如果您使用 glPixelZoom 來變更 xy 圖元縮放因數,圖元會轉換成片段,如下所示。 如果 (xr,yr) 是目前的點陣位置,而指定的圖元位於圖元矩形的第 n個數據行和 第 m列,則會針對位於角落的矩形中圖元產生片段

(xr + 縮放nyr + zoomym)

(xr + 縮放? (n + 1) ,yr + 縮放y (m + 1) )

在哪裡 縮放?是 GL_ZOOM_X 的值, 縮放y 是 GL_ZOOM_Y 的值。

下列函式會擷 取與 glDrawPixels相關的資訊:

glGet with argument GL_CURRENT_RASTER_POSITION

glGet with argument GL_CURRENT_RASTER_POSITION_VALID

規格需求

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

另請參閱

glAlphaFunc

glBegin

glBlendFunc

glCopyPixels

glDepthFunc

glEnd

glGet

glLogicOp

glPixelMap

glPixelStore

glPixelTransfer

glPixelZoom

glRasterPos

glReadPixels

glScissor

glStencilFunc