MaskBlt 函式 (wingdi.h)

發行項
03/13/2024

MaskBlt 函式會使用指定的遮罩和點陣作業，結合來源和目的地點陣的色彩數據。

語法

BOOL MaskBlt(
  [in] HDC     hdcDest,
  [in] int     xDest,
  [in] int     yDest,
  [in] int     width,
  [in] int     height,
  [in] HDC     hdcSrc,
  [in] int     xSrc,
  [in] int     ySrc,
  [in] HBITMAP hbmMask,
  [in] int     xMask,
  [in] int     yMask,
  [in] DWORD   rop
);

參數

[in] hdcDest

目的地裝置內容的句柄。

[in] xDest

目的地矩形左上角的 X 座標，以邏輯單位表示。

[in] yDest

目的地矩形左上角的 Y 座標，以邏輯單位表示。

[in] width

目的地矩形和來源位圖的寬度，以邏輯單位表示。

[in] height

目的地矩形和來源位圖的高度，以邏輯單位表示。

[in] hdcSrc

要從中複製位圖之裝置內容的句柄。如果 dwRop 參數指定不包含來源的點陣作業，它就必須是零。

[in] xSrc

來源位圖左上角的 X 座標，以邏輯單位表示。

[in] ySrc

來源位圖左上角的 Y 座標，以邏輯單位表示。

[in] hbmMask

單色遮罩位圖的句柄，結合來源裝置內容中的色彩點陣圖。

[in] xMask

hbmMask 參數所指定遮罩位圖的水準圖元位移。

[in] yMask

hbmMask 參數所指定遮罩位圖的垂直圖元位移。

[in] rop

函式用來控制來源和目的地數據組合 (ROP) 前景和背景三元點陣作業程序代碼。背景點陣作業程式代碼會儲存在此值高序單字的高序位元組中;前景點陣作業程序代碼會以此值高序單字的低序位元組儲存;忽略這個值的低序字組，而且應該是零。宏 MAKEROP4 建立前景和背景點陣作業程式代碼的這類組合。

如需此函式內容中前景和背景的討論，請參閱下列一節。

如需一般點陣作業代碼的清單， (ROP) ，請參閱 BitBlt 函式。請注意，CAPTUREBLT ROP 通常無法用於列印裝置內容。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。

備註

MaskBlt 函式會使用裝置相依點陣圖。

hbmMask 所指定遮罩中的值 1 表示應該在該位置套用 dwRop 所指定的前景點陣作業程序代碼。遮罩中的值 0 表示 dwRop 所指定的背景點陣作業程式代碼應該套用到該位置。

如果點陣作業需要來源，遮罩矩形必須涵蓋來源矩形。如果沒有，函式將會失敗。如果點陣作業不需要來源，遮罩矩形必須涵蓋目的矩形。如果沒有，函式將會失敗。

如果呼叫此函式時，來源裝置內容的旋轉或變換轉換生效，就會發生錯誤。不過，允許其他類型的轉換。

如果來源、圖樣和目的地位圖的色彩格式不同，此函式會轉換模式或來源格式，或兩者都符合目的格式。

如果遮罩位圖不是單色位圖，就會發生錯誤。

記錄增強型元檔時，如果來源裝置內容識別增強型元檔裝置內容，就會 (發生錯誤，且函式會傳回 FALSE) 。

並非所有裝置都支援 MaskBlt 函式。應用程式應該使用 nIndex 參數呼叫 GetDeviceCaps 函式作為RC_BITBLT，以判斷裝置是否支援此函式。

如果未提供遮罩位圖，則此函式的行為與 BitBlt 完全相同，使用前景點陣作業程序代碼。

Icm： Blits 發生時不會執行色彩管理。

在多個監視器系統中使用時， hdcSrc 和 hdcDest 都必須參考相同的裝置，否則函式將會失敗。若要在不同裝置的 DC 之間傳輸數據，請呼叫 GetDIBits，將記憶體位圖 (相容的點陣圖或 DDB) 轉換成 DIB。若要向第二個裝置顯示 DIB，請呼叫 SetDIBits 或 StretchDIBits。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	wingdi.h (包含 Windows.h)
程式庫	Gdi32.lib
Dll	Gdi32.dll