DrvSetPointerShape-Funktion (winddi.h)

Artikel
01/10/2024

Die DrvSetPointerShape-Funktion wird verwendet, um den Treiber anzufordern, den Zeiger vom Display zu nehmen, wenn der Treiber ihn dorthin gezeichnet hat; , um zu versuchen, eine neue Zeigerform festzulegen; und, um den neuen Zeiger an einer angegebenen Position auf dem Display zu platzieren.

Syntax

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

Parameter

[in] pso

Zeiger auf eine SURFOBJ-Struktur , die die Zu zeichnende Oberfläche beschreibt.

[in] psoMask

Zeiger auf die SURFOBJ-Struktur, die die AND-XOR-Maske definiert. (Die AND-XOR-Maske wird unter Zeichnen monochromer Zeiger beschrieben.) Die Dimensionen dieser Bitmap bestimmen die Größe des Zeigers. Es gibt keine impliziten Einschränkungen für Zeigergrößen, aber die optimalen Zeigergrößen sind 32 x 32, 48 x 48 und 64 x 64 Pixel. Wenn dieser Parameter NULL ist, ist der Zeiger transparent.

[in] psoColor

Zeiger auf die SURFOBJ-Struktur, die die Farben für einen Farbzeiger definiert. Wenn dieser Parameter NULL ist, ist der Zeiger monochrom. Die Zeiger-Bitmap hat die gleiche Breite wie psoMask und die halbe Höhe.

[in] pxlo

Zeiger auf eine XLATEOBJ-Struktur , die die Farben in psoColor definiert.

[in] xHot

Geben Sie die x-Position des Hotspots des Zeigers relativ zum linken oberen Pixel an. Das durch den Hotspot angegebene Pixel sollte an der neuen Zeigerposition positioniert werden.

[in] yHot

Geben Sie die y-Position des Hotspots des Zeigers relativ zum linken oberen Pixel an. Das durch den Hotspot angegebene Pixel sollte an der neuen Zeigerposition positioniert werden.

[in] x

Geben Sie die x-Koordinate der neuen Zeigerposition an.

[in] y

Geben Sie die y-Koordinate der neuen Zeigerposition an.

[in] prcl

Gibt die RECTL-Struktur an, die den Speicherort angibt, an dem der Treiber ein Rechteck schreiben soll, das eine enge Bindung für den sichtbaren Teil des Zeigers angibt.

[in] fl

Gibt einen erweiterbaren Satz von Flags an. Der Treiber sollte den Aufruf ablehnen, wenn Flags festgelegt sind, die er nicht versteht. Dieser Parameter kann mindestens einen der folgenden vordefinierten Werte und mindestens einen vom Treiber definierten Wert sein:

Flag	Bedeutung
SPS_ALPHA	Der Zeiger weist Alphawerte pro Pixel auf.
SPS_ANIMATESTART	Der Treiber sollte darauf vorbereitet sein, eine Reihe von Zeigerformen ähnlicher Größe zu erhalten, die einen animierten Zeigereffekt umfassen.
SPS_ANIMATEUPDATE	Der Treiber sollte die nächste Zeigerform in der animierten Serie zeichnen.
SPS_ASYNCCHANGE	Dieses Flag ist veraltet. Bei Legacytreibern sollte der Treiber die Änderung nur akzeptieren, wenn er in der Lage ist, die Zeigerform in der Hardware zu ändern, während eine andere Zeichnung auf dem Gerät ausgeführt wird. GDI verwendet diese Option nur, wenn das jetzt veraltete GCAPS_ASYNCCHANGE-Flag im flGraphicsCaps-Member der DEVINFO-Struktur festgelegt ist.
SPS_CHANGE	Der Treiber wird aufgefordert, die Zeigerform zu ändern.
SPS_FREQMASK	Der Treiber wird aufgefordert, einen Mauspfad zu rendern und das Bild so oft pro Millisekunde zu aktualisieren, wie im Ausdruck fl & SPS_FREQMASK angegeben. Für einen Treiber, der Mauspfade rendern kann, muss das GCAPS2_MOUSETRAILS-Flag im flGraphicsCaps2-Member seiner DEVINFO-Struktur festgelegt sein.
SPS_LENGTHMASK	Der Treiber wird aufgefordert, eine Mausspur mit der Länge zu rendern, die durch den Ausdruck fl & SPS_LENGTHMASK angegeben ist. (Eine Mausspur der Länge N besteht aus N + 1 Cursorbildern.) Für einen Treiber, der Mauspfade rendern kann, muss das GCAPS2_MOUSETRAILS-Flag im flGraphicsCaps2-Member seiner DEVINFO-Struktur festgelegt sein.

Rückgabewert

Der Rückgabewert kann einer der folgenden Werte sein:

Rückgabecode	Beschreibung
SPS_ACCEPT_EXCLUDE	Ist veraltet. GDI deaktiviert den Zeiger des Treibers und rückgängig machen zur Softwaresimulation, wenn der Treiber diesen Wert zurückgibt.
SPS_ACCEPT_NOEXCLUDE	Der Treiber akzeptiert die Form. Das Shape wird in der Hardware unterstützt, und GDI ist nicht besorgt, dass andere Zeichnungen den Zeiger überschreiben.
SPS_DECLINE	Der Treiber unterstützt das Shape nicht, daher muss GDI es simulieren.
SPS_ERROR	Der Treiber unterstützt diese Form normalerweise, ist aber aus ungewöhnlichen Gründen nicht erfolgreich.

Hinweise

DrvSetPointerShape ist optional für Anzeigetreiber. Wenn diese Funktion implementiert ist, muss jedoch auch DrvMovePointer implementiert werden.

Die iUniq-Elemente der SURFOBJ-Strukturen, auf die psoMask und psoColor-Punkt für eindeutige Zeiger eindeutig sind. Der Treiber kann diese Informationen in Verbindung mit den eindeutigen dhsurf-Handles dieser Strukturen als Cacheschlüssel für die Cursorzwischenspeicherung verwenden.

Wenn SPS_ALPHA im fl-Parameter festgelegt ist, ist psoMaskNULL und psoColor zeigt auf eine 32-Bitpp-BGRA-Oberfläche. Der Alphawert pro Pixel gibt die Deckkraft des entsprechenden Zeigerpixels mit dem darunter zugehörigen Desktoppixel an. Das Quell-Alphaformat ist vormultipliziert. Das heißt, jeder Farbkanal der Quelloberfläche wurde bereits mit dem entsprechenden Alphawert vormultipliziert, wodurch ein Multiplikationsvorgang zum Zeitpunkt der Mischung beseitigt wurde.

Die Standard-Alphacursor sind größtenteils schwarzweiß mit einem großen Bereich von Alphawerten; Es gibt jedoch keine Farbeinschränkung, da Anwendungen beliebige Cursor selbst angeben können. Typische Alphazeigergrößen sind ca. 8 Pixel größer als typische Zeiger ohne Alpha. Dadurch wird der Schatteneffekt berücksichtigt, der durch einen Verwischungsfilter erreicht wird, der die resultierende Zeiger-Bitmap-Form erweitert. Die überwiegende Mehrheit der Zeiger sind Bitmaps mit 64 x 64 Pixeln oder kleiner.

Der Treiber gibt seine Fähigkeit an, Zeiger mit Alphawerten pro Pixel zu behandeln, indem er das GCAPS2_ALPHACURSOR-Flag im flGraphicsCaps2-Member der DEVINFO-Struktur festlegt, die von DrvEnablePDEV zurückgegeben wird.