Fonction DrvSetPointerShape (winddi.h)

Article
08/27/2023

La fonction DrvSetPointerShape est utilisée pour demander au pilote de retirer le pointeur de l’affichage, si le pilote l’a dessiné à cet emplacement ; pour tenter de définir une nouvelle forme de pointeur ; et pour placer le nouveau pointeur sur l’affichage à une position spécifiée.

Syntaxe

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

Paramètres

[in] pso

Pointeur vers une structure SURFOBJ qui décrit la surface sur laquelle dessiner.

[in] psoMask

Pointeur vers la structure SURFOBJ qui définit le masque AND-XOR. (Le masque AND-XOR est décrit dans Dessin de pointeurs monochromes.) Les dimensions de cette bitmap déterminent la taille du pointeur. Il n’existe aucune contrainte implicite sur les tailles de pointeur, mais les tailles de pointeur optimales sont de 32 x 32, 48 x 48 et 64 x 64 pixels. Si ce paramètre a la valeur NULL, le pointeur est transparent.

[in] psoColor

Pointeur vers la structure SURFOBJ qui définit les couleurs d’un pointeur de couleur. Si ce paramètre a la valeur NULL, le pointeur est monochrome. La bitmap de pointeur a la même largeur que psoMask et la moitié de la hauteur.

[in] pxlo

Pointeur vers une structure XLATEOBJ qui définit les couleurs dans psoColor.

[in] xHot

Spécifiez la position x du point chaud du pointeur par rapport à son pixel supérieur gauche. Le pixel indiqué par le point chaud doit être positionné à la nouvelle position du pointeur.

[in] yHot

Spécifiez la position y du point chaud du pointeur par rapport à son pixel supérieur gauche. Le pixel indiqué par le point chaud doit être positionné à la nouvelle position du pointeur.

[in] x

Spécifiez la coordonnée x de la nouvelle position du pointeur.

[in] y

Spécifiez la coordonnée y de la nouvelle position du pointeur.

[in] prcl

Spécifie la structure RECTL qui indique l’emplacement dans lequel le pilote doit écrire un rectangle qui spécifie une limite étroite pour la partie visible du pointeur.

[in] fl

Spécifie un ensemble extensible d’indicateurs. Le pilote doit refuser l’appel si des indicateurs sont définis qu’il ne comprend pas. Ce paramètre peut être une ou plusieurs des valeurs prédéfinies suivantes et une ou plusieurs valeurs définies par le pilote :

Indicateur	Signification
SPS_ALPHA	Le pointeur a des valeurs alpha par pixel.
SPS_ANIMATESTART	Le pilote doit être prêt à recevoir une série de formes de pointeur de taille similaire qui comprendront un effet de pointeur animé.
SPS_ANIMATEUPDATE	Le pilote doit dessiner la forme de pointeur suivante dans la série animée.
SPS_ASYNCCHANGE	Cet indicateur est obsolète. Pour les pilotes hérités, le pilote doit accepter la modification uniquement s’il est capable de modifier la forme du pointeur dans le matériel pendant que d’autres dessins sont en cours sur l’appareil. GDI utilise cette option uniquement si l’indicateur de GCAPS_ASYNCCHANGE désormais obsolète est défini dans le membre flGraphicsCaps de la structure DEVINFO .
SPS_CHANGE	Le pilote est invité à modifier la forme du pointeur.
SPS_FREQMASK	Le pilote est invité à restituer une trace de souris, en mettant à jour l’image autant de fois par milliseconde qu’indiqué dans l’expression fl & SPS_FREQMASK. Un pilote capable de rendre des traces de souris doit avoir l’indicateur GCAPS2_MOUSETRAILS défini dans le membre flGraphicsCaps2 de sa structure DEVINFO .
SPS_LENGTHMASK	Le pilote est invité à restituer une piste de souris de longueur indiquée par l’expression fl & SPS_LENGTHMASK. (Une trace de souris de longueur N est composée d’images de curseur N + 1.) Un pilote capable de rendre des traces de souris doit avoir l’indicateur GCAPS2_MOUSETRAILS défini dans le membre flGraphicsCaps2 de sa structure DEVINFO .

Valeur retournée

La valeur de retour peut être l’une des valeurs suivantes :

Code de retour	Description
SPS_ACCEPT_EXCLUDE	Est obsolète. GDI désactive le pointeur du pilote et rétablit la simulation logicielle si le pilote retourne cette valeur.
SPS_ACCEPT_NOEXCLUDE	Le pilote accepte la forme. La forme est prise en charge dans le matériel et GDI ne se préoccupe pas des autres dessins qui remplacent le pointeur.
SPS_DECLINE	Comme le pilote ne prend pas en charge la forme, GDI doit la simuler.
SPS_ERROR	Le pilote prend normalement en charge cette forme, mais a échoué pour des raisons inhabituelles.

Remarques

DrvSetPointerShape est facultatif pour les pilotes d’affichage. Toutefois, si cette fonction est implémentée, DrvMovePointer doit également être implémenté.

Les membres iUniq des structures SURFOBJ auxquelles psoMask et psoColor point sont uniques pour les pointeurs uniques. Le pilote peut utiliser ces informations conjointement avec les handles dhsurf uniques de ces structures en tant que clés de cache pour la mise en cache des curseurs.

Quand SPS_ALPHA est défini dans le paramètre fl , psoMask a la valeur NULL et psoColor pointe vers une surface BGRA de 32 bpp. La valeur alpha par pixel indique l’opacité du pixel de pointeur correspondant avec le pixel du bureau en dessous. Le format alpha source est prémultiplié ; autrement dit, chacun des canaux de couleur de la surface source a déjà été prémultiplié avec la valeur alpha correspondante, éliminant ainsi une opération de multiplication au moment du mélange.

Les curseurs alpha par défaut sont en grande partie noir et blanc avec une large plage de valeurs alpha ; toutefois, il n’existe aucune restriction de couleur, car les applications peuvent spécifier elles-mêmes des curseurs arbitraires. Les tailles de pointeur alpha typiques sont d’environ 8 pixels plus grandes en dimension que les pointeurs classiques sans alpha. Cela prend en charge l’effet d’ombre, qui est effectué par un filtre de flou qui développe la forme bitmap de pointeur résultante. La grande majorité des pointeurs seront des bitmaps de 64 x 64 pixels ou plus petits.

Le pilote indique sa capacité à gérer des pointeurs avec des valeurs alpha par pixel en définissant l’indicateur GCAPS2_ALPHACURSOR dans le membre flGraphicsCaps2 de la structure DEVINFO retourné par DrvEnablePDEV.