共用方式為

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座標和紋理座標附加至每個圖元，然後將x和y視窗座標指派給第 n個片段，以轉換成片段？」 = xr + n mod寬度
    y？ = yr + n/width
    其中 (xr ， yr ) 是目前的點陣位置。
  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函式會將目前點陣位置色彩或色彩索引和紋理座標附加至每個圖元，然後將x和y視窗座標指派給第 n個片段，以將產生的深度元件轉換成片段？」 = xr + n mod寬度
    y？ = yr + n/width
    其中 ( xr ，yr ) 是目前的點陣位置。
  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座標和紋理座標附加至每個圖元，然後將x和y視窗座標指派給第 n個片段，以將產生的 RGBA 色彩轉換成片段？」 = xr + n mod寬度
    y？ = yr + n /width
    其中 (xr ，yr ) 是目前的點陣位置。
  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來查詢點陣位置。

數個參數會定義記憶體中的圖元資料編碼，並控制圖元資料的處理，再將其放在框架緩衝區中。 這些參數會設定為四個函式：glPixelStore、glPixelTransfer、glPixelMap 和 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函式會根據glPixelTransfer和glPixelMap所指定的數個參數值，以相同方式在記憶體中讀取的每個寬度高度圖元上運作。 這些作業的詳細資料，以及繪製圖元的目標緩衝區，都是以 格式指定的像素格式所特有。

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

(xr + 縮放？n， yr + 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