DrvBitBlt-Funktion (winddi.h)

Artikel
08/27/2023

Die DrvBitBlt-Funktion bietet allgemeine Bitblockübertragungsfunktionen zwischen geräteverwalteten Oberflächen, zwischen von GDI verwalteten Standardformat-Bitmaps oder zwischen einer geräteseitig verwalteten Oberfläche und einer von GDI verwalteten Standardformatbitbit.

Syntax

BOOL DrvBitBlt(
  [in, out]      SURFOBJ  *psoTrg,
  [in, optional] SURFOBJ  *psoSrc,
  [in, optional] SURFOBJ  *psoMask,
  [in]           CLIPOBJ  *pco,
  [in, optional] XLATEOBJ *pxlo,
  [in]           RECTL    *prclTrg,
  [in, optional] POINTL   *pptlSrc,
  [in, optional] POINTL   *pptlMask,
  [in, optional] BRUSHOBJ *pbo,
  [in, optional] POINTL   *pptlBrush,
  [in]           ROP4     rop4
);

Parameter

[in, out] psoTrg

Zeiger auf die SURFOBJ-Struktur , die die Oberfläche beschreibt, auf der gezeichnet werden soll.

[in, optional] psoSrc

Zeiger auf eine SURFOBJ-Struktur, die die Quelle für den Bitblockübertragungsvorgang beschreibt, falls für den rop4-Parameter erforderlich.

[in, optional] psoMask

Zeiger auf eine SURFOBJ-Struktur, die eine Oberfläche beschreibt, die als Maske für den rop4-Parameter verwendet werden soll. Die Maske ist eine Bitmap mit 1 Bit pro Pixel. In der Regel wird eine Maske verwendet, um den zu ändernden Bereich auf der Zieloberfläche einzuschränken. Die Maskierung wird ausgewählt, indem der rop4-Parameter auf den Wert 0xAACC festgelegt wird. Die Zieloberfläche ist nicht betroffen, wenn die Maske 0x0000 ist.

Die Maske ist groß genug, um das Zielrechteck abzudecken.

Wenn dieser Parameter NULL ist und für den rop4-Parameter eine Maske erforderlich ist, wird die implizite Maske im Pinsel verwendet.

[in] pco

Zeiger auf eine CLIPOBJ-Struktur , die den zu ändernden Bereich einschränkt. GDI-Dienste (CLIPOBJXxx), die den Clipbereich als Eine Reihe von Rechtecken auflisten, werden bereitgestellt. Wann immer möglich, vereinfacht GDI den Ausschnitt; Beispielsweise wird diese Funktion nie mit einem einzelnen Clippingrechteck aufgerufen. GDI schneidet das Zielrechteck ab, bevor diese Funktion aufgerufen wird, sodass zusätzliche Beschneidung unnötig ist.

[in, optional] pxlo

Zeiger auf eine XLATEOBJ-Struktur , die angibt, wie Farbindizes zwischen der Quell- und der Zieloberfläche übersetzt werden sollen. Wenn pxloNULL ist, ist keine Übersetzung erforderlich.

Wenn die Quelloberfläche palettenverwaltet ist, werden ihre Farben durch Indizes in einer Nachschlagetabelle mit RGB-Werten dargestellt. Die XLATEOBJ-Struktur kann nach einem Übersetzungsvektor abgefragt werden, der es dem Gerätetreiber ermöglicht, einen beliebigen Quellindex in einen Farbindex für das Ziel zu übersetzen.

Die Situation ist komplizierter, wenn z. B. die Quelle RGB ist, aber das Ziel palettenseitig verwaltet wird. In diesem Fall muss die nächstgelegene Übereinstimmung mit jedem RGB-Quellwert in der Zielpalette gefunden werden. Der Treiber kann den XLATEOBJ_iXlate-Dienst aufrufen, um diesen Vorgang auszuführen.

Optional kann der Gerätetreiber Farben abgleichen, wenn die Zielpalette die Standardgerätepalette ist.

[in] prclTrg

Zeiger auf eine RECTL-Struktur , die den zu ändernden Bereich definiert. Diese Struktur verwendet das Koordinatensystem der Zieloberfläche. Der untere und rechte Rand dieses Rechtecks sind nicht Teil der Bitblockübertragung, d. h. das Rechteck ist unten rechts exklusiv.

DrvBitBlt wird nie mit einem leeren Zielrechteck aufgerufen. Die beiden Punkte, die das Rechteck definieren, sind immer gut sortiert. Auf Multimonitorsystemen kann das Rechteck jedoch einen Bereich definieren, der größer als die Zieloberfläche ist. Treiber sollten dieses Rechteck mit ihrer Oberfläche überschneiden.

[in, optional] pptlSrc

Zeiger auf eine POINTL-Struktur , die die obere linke Ecke des Quellrechtecks definiert, sofern eine Quelle vorhanden ist. Dieser Parameter wird ignoriert, wenn keine Quelle vorhanden ist.

[in, optional] pptlMask

Zeiger auf eine POINTL-Struktur, die definiert, welches Pixel in der Maske der oberen linken Ecke des Quellrechtecks entspricht, sofern eine Quelle vorhanden ist. Dieser Parameter wird ignoriert, wenn der psoMask-ParameterNULL ist.

[in, optional] pbo

Zeiger auf eine BRUSHOBJ-Struktur , die das Muster für die Bitblockübertragung definiert. Der BRUSHOBJ_pvGetRbrush-Dienst von GDI kann verwendet werden, um die Realisierung des Pinsels des Geräts abzurufen. Dieser Parameter wird ignoriert, wenn der rop4-Parameter kein Muster erfordert.

[in, optional] pptlBrush

Zeiger auf eine POINTL-Struktur , die den Ursprung des Pinsels auf der Zieloberfläche definiert. Das obere linke Pixel des Pinsels wird an dieser Stelle ausgerichtet, und der Pinsel wiederholt sich entsprechend seinen Abmessungen. Dieser Parameter wird ignoriert, wenn der rop4-Parameter kein Muster erfordert.

[in] rop4

Gibt einen Rastervorgang an, der definiert, wie die Masken-, Muster-, Quell- und Zielpixel kombiniert werden, um auf die Zieloberfläche zu schreiben.

Dies ist eine quartäre Rasteroperation, die eine Erweiterung des ternären Rop3-Vorgangs ist. Ein Rop4 hat 16 relevante Bits, die den 8 definierenden Bits eines Rop3 ähneln. Die einfachste Möglichkeit zum Implementieren eines Rop4 besteht darin, seine 2 Bytes separat zu betrachten: Das niedrige Byte gibt einen Rop3 an, der berechnet werden soll, wenn die Maske eins ist, und das hohe Byte gibt einen Rop3 an, der berechnet und angewendet werden kann, wenn die Maske 0 ist.

Rückgabewert

DrvBitBlt gibt TRUE zurück, wenn der Bitblockübertragungsvorgang erfolgreich ist. Andernfalls gibt die Funktion FALSE zurück, und ein Fehlercode wird protokolliert.

Hinweise

Wenn der Treiber DrvBitBlt einhakt, ruft GDI diese Funktion auf, wenn ein BitBlt-Vorgang ausgeführt werden muss, wobei eine der Oberflächen eine geräteseitig verwaltete Oberfläche ist. Wenn der Treiber undurchsichtige, vom Gerät verwaltete Bitmaps implementiert, muss er DrvBitBlt einbinden. Andernfalls ist das Einbinden von DrvBitBlt optional. Wenn der Treiber den angegebenen Aufruf nicht verarbeiten kann, kann der Rückruf an die DIB-Engine durch Aufrufen von EngBitBlt erfolgen.

Die CLIPOBJXxx-Dienste von GDI ermöglichen es, das Clipping auf eine Reihe von Beschneidungsrechtecke zu reduzieren. Ein Übersetzungsvektor unterstützt die Farbindexübersetzung für Paletten.

Hinweis Dereferenzieren Sie keine Parameterzeiger, es sei denn, der ROP gibt an, dass sie benötigt werden. Beispiel: Niemals unnötig dereferenzieren pbo--iSolidColor>, da dies für ein ROP wie BLACKNESS zu einer Zugriffsverletzung führen kann. (Diese Regel gilt auch für jede Funktion, die einen MIX-Parameter enthält.)

Wenn der Treiber einen Aufruf dieser Funktion empfängt, bei dem der rop4-Parameter auf 0XCCAA festgelegt ist, sollte der Treiber den Aufruf von EngBitBlt durchpubtieren und die Geräteoberflächen entsprechend dem Aufruf verfügbar machen.

Weitere Informationen zu Rastervorgängen finden Sie in der Dokumentation zu Microsoft Windows SDK.