DrvSetPointerShape 函式 (winddi.h)

發行項
01/10/2024

DrvSetPointerShape 函式可用來要求驅動程式將指標從顯示器上取出，如果驅動程式已在該處繪製它;嘗試設定新的指標圖形;和，將新的指標放在顯示器上的指定位置。

語法

ULONG DrvSetPointerShape(
  [in] SURFOBJ  *pso,
  [in] SURFOBJ  *psoMask,
  [in] SURFOBJ  *psoColor,
  [in] XLATEOBJ *pxlo,
  [in] LONG     xHot,
  [in] LONG     yHot,
  [in] LONG     x,
  [in] LONG     y,
  [in] RECTL    *prcl,
  [in] FLONG    fl
);

參數

[in] pso

SURFOBJ 結構的指標，描述要繪製的介面。

[in] psoMask

定義 AND-XOR 遮罩之 SURFOBJ 結構的指標。 (繪圖單色指標中會描述 AND-XOR 遮罩。) 此點陣圖的維度會決定指標的大小。指標大小沒有隱含條件約束，但最佳指標大小為 32 x 32、48 x 48 和 64 x 64 像素。如果此參數為 NULL，則指標是透明的。

[in] psoColor

SURFOBJ 結構的指標，定義色彩指標的色彩。如果此參數為 NULL，則指標為單色。指標點圖的寬度與 psoMask 和一半的高度相同。

[in] pxlo

XLATEOBJ 結構的指標，定義 psoColor 中的色彩。

[in] xHot

指定指標作用點相對於其左上方圖元的 x 位置。作用點所指示的像素應該位於新的指標位置。

[in] yHot

指定指標作用點相對於其左上方圖元的 Y 位置。作用點所指示的像素應該位於新的指標位置。

[in] x

指定新指標位置的 X 座標。

[in] y

指定新指標位置的 Y 座標。

[in] prcl

指定 RECTL 結構，指出驅動程式應該撰寫矩形的位置，指定指標可見部分的緊密界限。

[in] fl

指定一組可延伸的旗標。如果有任何旗標設定為無法理解的旗標，驅動程式應該拒絕呼叫。此參數可以是下列一或多個預先定義的值，以及一或多個驅動程式定義的值：

旗標	意義
SPS_ALPHA	指標具有每圖元 Alpha 值。
SPS_ANIMATESTART	驅動程式應該準備好接收一系列類似大小的指標圖形，這些圖形將組成動畫指標效果。
SPS_ANIMATEUPDATE	驅動程式應該會在動畫數列中繪製下一個指標圖形。
SPS_ASYNCCHANGE	這個旗標已過時。對於舊版驅動程式，只有在驅動程式能夠在裝置上進行其他繪圖時變更硬體中的指標圖形時，驅動程式才接受變更。只有在 DEVINFO 結構的 flGraphicsCaps 成員中設定了目前過時GCAPS_ASYNCCHANGE旗標時，GDI 才會使用此選項。
SPS_CHANGE	系統會要求驅動程式變更指標圖形。
SPS_FREQMASK	系統會要求驅動程序轉譯滑鼠尾端，每毫秒更新影像的次數，如表達式 fl & SPS_FREQMASK 所示。能夠轉譯滑鼠線索的驅動程序必須在其 DEVINFO 結構的 flGraphicsCaps2 成員中設定GCAPS2_MOUSETRAILS旗標。
SPS_LENGTHMASK	系統會要求驅動程序轉譯表達式 fl & SPS_LENGTHMASK 所指出長度的滑鼠尾端。 (長度 N 的滑鼠尾端是由 N + 1 個游標影像所組成。) 能夠轉譯滑鼠線索的驅動程式必須在其 DEVINFO 結構的 flGraphicsCaps2 成員中設定GCAPS2_MOUSETRAILS旗標。

傳回值

傳回值可以是下列其中一個值：

傳回碼	Description
SPS_ACCEPT_EXCLUDE	已過時。如果驅動程式傳回此值，GDI 將會停用驅動程式的指標，並還原為軟體模擬。
SPS_ACCEPT_NOEXCLUDE	驅動程式接受圖形。硬體支持圖形，GDI 並不擔心其他覆寫指標的繪圖。
SPS_DECLINE	驅動程式不支援圖形，因此 GDI 必須模擬它。
SPS_ERROR	驅動程式通常支援此圖形，但基於不尋常的原因而失敗。

備註

DrvSetPointerShape 是顯示驅動程式的選擇性專案。不過，如果實作此函式，也必須實作 DrvMovePointer 。

psoMask 和 psoColor 點對於唯一指標而言，SURFOBJ 結構的 iUniq 成員。驅動程式可以使用這項資訊搭配這些結構的唯一 dhsurf 句柄作為數據指標快取的快取索引鍵。

在 fl 參數中設定SPS_ALPHA時，psoMask 為 NULL，psoColor 會指向 32bpp BGRA 表面。每像素 Alpha 值表示對應指標圖元的不透明度，其下方是桌面圖元。來源 Alpha 格式為預先乘法;也就是說，來源表面的每個色彩色板都已經預先乘以對應的Alpha值，因此在混合時消除乘法運算。

默認Alpha游標大為黑色和白色，具有大量的Alpha值;不過，沒有色彩限制，因為應用程式可以自行指定任意數據指標。一般的 Alpha 指標大小大約是維度中的 8 像素，比不含 Alpha 的一般指標還要大。這可容納陰影效果，這是透過模糊篩選來展開產生的指標點圖圖形來完成。大部分的指標都會是64x64像素點陣圖或更小。

驅動程式會藉由在DrvEnablePDEV所傳回之DEVINFO結構的 flGraphicsCaps2 成員中設定GCAPS2_ALPHACURSOR旗標，指出其能夠處理具有每個圖元 Alpha 值的指標。