Funzione DrvSetPointerShape (winddi.h)

Articolo
01/10/2024

La funzione DrvSetPointerShape viene usata per richiedere al driver di togliere il puntatore dallo schermo, se il driver l'ha disegnato; per tentare di impostare una nuova forma del puntatore; e per inserire il nuovo puntatore sullo schermo in una posizione specificata.

Sintassi

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
);

Parametri

[in] pso

Puntatore a una struttura SURFOBJ che descrive la superficie su cui disegnare.

[in] psoMask

Puntatore alla struttura SURFOBJ che definisce la maschera AND-XOR. La maschera AND-XOR è descritta in Disegno di puntatori monocromatici. Le dimensioni di questa bitmap determinano le dimensioni del puntatore. Non esistono vincoli impliciti per le dimensioni del puntatore, ma le dimensioni ottimali del puntatore sono 32 x 32, 48 x 48 e 64 x 64 pixel. Se questo parametro è NULL, il puntatore è trasparente.

[in] psoColor

Puntatore alla struttura SURFOBJ che definisce i colori per un puntatore a colori. Se questo parametro è NULL, il puntatore è monocromatico. La bitmap del puntatore ha la stessa larghezza di psoMask e metà dell'altezza.

[in] pxlo

Puntatore a una struttura XLATEOBJ che definisce i colori in psoColor.

[in] xHot

Specificare la posizione x del punto attivo del puntatore rispetto al pixel superiore sinistro. Il pixel indicato dal punto attivo deve essere posizionato nella nuova posizione del puntatore.

[in] yHot

Specificare la posizione y dello spot attivo del puntatore rispetto al pixel superiore sinistro. Il pixel indicato dal punto attivo deve essere posizionato nella nuova posizione del puntatore.

[in] x

Specificare la coordinata x della nuova posizione del puntatore.

[in] y

Specificare la coordinata y della nuova posizione del puntatore.

[in] prcl

Specifica la struttura RECTL che indica la posizione in cui il driver deve scrivere un rettangolo che specifica un limite stretto per la parte visibile del puntatore.

[in] fl

Specifica un set estendibile di flag. Il driver deve rifiutare la chiamata se vengono impostati flag che non riconosce. Questo parametro può essere uno o più dei valori predefiniti seguenti e uno o più valori definiti dal driver:

Contrassegno	Significato
SPS_ALPHA	Il puntatore ha valori alfa per pixel.
SPS_ANIMATESTART	Il driver deve essere preparato a ricevere una serie di forme puntatore di dimensioni simili che comprenderanno un effetto puntatore animato.
SPS_ANIMATEUPDATE	Il driver deve disegnare la forma del puntatore successiva nella serie animata.
SPS_ASYNCCHANGE	Questo flag è obsoleto. Per i driver legacy, il driver deve accettare la modifica solo se è in grado di modificare la forma del puntatore nell'hardware mentre è in corso un altro disegno nel dispositivo. GDI usa questa opzione solo se il flag GCAPS_ASYNCCHANGE obsoleto è impostato nel membro flGraphicsCaps della struttura DEVINFO .
SPS_CHANGE	Il driver deve modificare la forma del puntatore.
SPS_FREQMASK	Il driver viene richiesto di eseguire il rendering di una traccia del mouse, aggiornando l'immagine il numero di volte al millisecondo indicato nell'espressione fl & SPS_FREQMASK. Un driver in grado di eseguire il rendering dei percorsi del mouse deve avere il flag GCAPS2_MOUSETRAILS impostato nel membro flGraphicsCaps2 della relativa struttura DEVINFO .
SPS_LENGTHMASK	Il driver viene richiesto di eseguire il rendering di una traccia del mouse di lunghezza indicata dall'espressione fl & SPS_LENGTHMASK. (Una traccia del mouse di lunghezza N è costituita da N + 1 immagini di cursore). Un driver in grado di eseguire il rendering dei percorsi del mouse deve avere il flag GCAPS2_MOUSETRAILS impostato nel membro flGraphicsCaps2 della relativa struttura DEVINFO .

Valore restituito

Il valore restituito può essere uno dei valori seguenti:

Codice restituito	Descrizione
SPS_ACCEPT_EXCLUDE	Obsoleto. GDI disabilita il puntatore del driver e ripristina la simulazione software se il driver restituisce questo valore.
SPS_ACCEPT_NOEXCLUDE	Il driver accetta la forma. La forma è supportata nell'hardware e GDI non è preoccupata per altri disegni sovrascrivendo il puntatore.
SPS_DECLINE	Il driver non supporta la forma, quindi GDI deve simularlo.
SPS_ERROR	Il driver supporta normalmente questa forma, ma non è riuscito per motivi insoliti.

Commenti

DrvSetPointerShape è facoltativo per i driver di visualizzazione. Se questa funzione viene implementata, tuttavia, è necessario implementare anche DrvMovePointer .

I membri iUniq delle strutture SURFOBJ a cui psoMask e punto psoColor sono unici per puntatori univoci. Il driver può usare queste informazioni insieme agli handle dhsurf univoci di queste strutture come chiavi della cache per la memorizzazione nella cache dei cursori.

Quando SPS_ALPHA è impostato nel parametro fl , psoMask è NULL e psoColor punta a una superficie BGRA a 32bpp. Il valore alfa per pixel indica l'opacità del pixel del puntatore corrispondente con il pixel del desktop sottostante. Il formato alfa di origine è premoltiplicato; ovvero, ognuno dei canali di colore della superficie di origine è già stato premoltiplicato con il valore alfa corrispondente, eliminando così un'operazione di moltiplicazione al momento della fusione.

I cursori alfa predefiniti sono in gran parte neri e bianchi con una vasta gamma di valori alfa; Tuttavia, non esiste alcuna restrizione di colore perché le applicazioni possono specificare cursori arbitrari. Le dimensioni tipiche dei puntatori alfa sono di circa 8 pixel maggiori nella dimensione rispetto ai puntatori tipici senza alfa. In questo modo viene applicato l'effetto ombreggiatura, ottenuto da un filtro sfocatura che espande la forma bitmap del puntatore risultante. La maggior parte dei puntatori sarà 64x64 pixel bitmap o più piccola.

Il driver indica la possibilità di gestire puntatori con valori alfa per pixel impostando il flag GCAPS2_ALPHACURSOR nel membro flGraphicsCaps2 della struttura DEVINFO restituita da DrvEnablePDEV.