DrvEnableSurface-Funktion (winddi.h)

Artikel
03/04/2024

Die DrvEnableSurface-Funktion richtet eine Oberfläche ein, auf der gezeichnet werden soll, und ordnet sie einem bestimmten physischen Gerät zu.

Syntax

HSURF DrvEnableSurface(
  DHPDEV dhpdev
);

Parameter

dhpdev

Handle mit dem PDEV des physischen Geräts. Dies ist der Rückgabewert von DrvEnablePDEV. Der PDEV beschreibt das physische Gerät, für das eine Oberfläche erstellt werden soll.

Rückgabewert

Der Rückgabewert ist ein Handle, das die neu erstellte Oberfläche identifiziert. Andernfalls ist er 0, und ein Fehlercode wird protokolliert.

Hinweise

Es gibt zwei Methoden zum Vorbereiten einer Oberfläche für die Verwendung.

In dieser Methode, die empfohlen wird, erstellt der Treiber die Oberfläche durch einen Aufruf von EngCreateDeviceSurface. Nachdem GDI die Oberfläche erstellt und einen Handle an den Treiber zurückgibt, ruft der Treiber EngModifySurface auf, das die entsprechenden Hookflags festlegt und optional GDI über die Position der Oberfläche informiert.
Die zweite Methode ist die von Windows NT 4.0-Treibern verwendete Methode. In dieser Methode ruft der Treiber EngCreateBitmap auf. Nach diesem Aufruf ruft der Treiber EngAssociateSurface auf, um die Oberfläche dem physischen Anzeigegerät zuzuordnen. Mit dieser GDI-Funktion kann der Treiber angeben, welche Grafikausgaberoutinen für Bitmaps im Standardformat unterstützt werden. Ein Aufruf dieser Funktion kann nur erfolgen, wenn keine Oberfläche für das angegebene physische Gerät vorhanden ist. Wenn ein Windows 2000- oder höher-Treiber für die Ausführung unter Windows NT 4.0 zurückportiert wird, muss diese Methode verwendet werden. Wenn ein solcher Treiber auch unter Windows 2000 oder höher ausgeführt wird, sollte ein separater Codepfad im Treiber die erste Methode verwenden.
Bei Druckergeräten besteht die übliche Situation darin, dass GDI die Grafiken direkt auf einer GDI-Bitmap sammelt. Der Treiber sollte EngCreateBitmap aufrufen, sodass GDI Arbeitsspeicher für die Bitmap zuweisen kann.

Jedes vorhandene GDI-Bitmaphandle ist ein gültiger Oberflächenhandle.

Für Druckergrafik-DLLs , die von GDI verwaltete Oberflächen verwenden, sollte die DrvEnableSurface-FunktionEngCreateBitmap aufrufen und eine Flächengröße angeben, die groß genug ist, um eine gesamte physische Seite zu enthalten. Wenn dies fehlschlägt, sollten wiederholte Aufrufe von EngCreateBitmap mit abnehmender Oberflächengröße versucht werden, bis ein Aufruf erfolgreich ist. Die gültige Größe sollte als Eingabe für EngMarkBandingSurface angegeben werden, wodurch GDI informiert wird, dass Surface-Banding erforderlich ist.

Nachdem DrvEnableSurface ein Handle an eine primäre Oberfläche zurückgegeben hat, rufen Sie EngModifySurface oder EngAssociateSurface für dieses Handle nicht auf. Dies kann unter bestimmten Umständen zu einer Fehlerüberprüfung führen. Weitere Informationen finden Sie im Microsoft Knowledge Base-Artikel 330248.

DrvEnableSurface ist für Grafiktreiber erforderlich.