Behandeln von Fehlern

Die Direct3D- Version 10-Funktionen , die ein Benutzermodusanzeigetreiber implementiert, verfügen in der Regel über VOID für einen Rückgabeparametertyp. Die primäre Ausnahme von dieser Regel ist die CalcPrivateObjType Size-type-Funktion (z. B. die Funktion CalcPrivateResourceSize). Dieser Funktionstyp gibt einen SIZE_T Parametertyp zurück, der die Größe des Speicherbereichs angibt, den der Treiber zum Erstellen des bestimmten Objekttyps über die Funktion CreateObjType-type (z. B. CreateResource(D3D10)) benötigt.

Die Rückgabe von VOID verhindert, dass der Benutzermodusanzeigetreiber die Direct3D-Runtime auf herkömmliche Weise über Fehler benachrichtigt (d. a. über den Funktionsrückgabeparameter eines Benutzermodusanzeigetreibers). Stattdessen muss der Benutzermodusanzeigetreiber die Rückruffunktion pfnSetErrorCb der Direct3D-Runtime verwenden, um solche Informationen an die Runtime zurück zu übergeben. Die Runtime stellt einen Zeiger auf ihre pfnSetErrorCb in der D3D10DDI_CORELAYER_DEVICECALLBACKS-Struktur bereit, auf die das pUMCallbacks-Element der D3D10DDIARG_CREATEDEVICE-Struktur in einem Aufruf der CreateDevice(D3D10) -Funktion verweist.

Auf der Referenzseite für jede Benutzermodusanzeigetreiberfunktion werden die Fehler angegeben, die die Funktion über einen Aufruf von pfnSetErrorCb übergeben kann. Das heißt, wenn der Benutzermodusanzeigetreiber pfnSetErrorCb mit einem Fehlercode aufruft, der für die aktuelle Benutzermodusanzeigetreiberfunktion nicht zulässig ist, ermittelt die Laufzeit, dass die Fehlerbedingung kritisch ist und entsprechend handelt. Da die Runtime während der pfnSetErrorCb-Instanz angemessen funktioniert, sollten Sie nicht erwarten, dass Sie die Auswirkungen des Aufrufens von pfnSetErrorCb( E_FAIL ) rückgängig machen können, indem Sie etwas wie pfnSetErrorCb( S_OK ) aufrufen. Tatsächlich bestimmt die Runtime, dass S_OK genauso ungültig oder kritisch ist wie E_FAIL. Das Konzept eines S_OK Rückgabecode entspricht der Anzeigetreiberfunktion des Benutzermodus, die pfnSetErrorCb überhaupt nicht aufruft.

Wenn die Direct3D-Runtime feststellt, dass eine Fehlerbedingung kritisch ist, wird zuerst eine Aktion ausgeführt, indem sie den Fehler mit Dr. Watson protokolliert, dem Standarddebugger für post mortem (Just-in-Time). Die Runtime verliert das Gerät dann absichtlich, wodurch das Szenario des Empfangens des D3DDDIERR_DEVICEREMOVED Fehlercodes emuliert wird. Da der Treiber die Rückruffunktion pfnSetErrorCb aufrufen muss, ist die Wahrscheinlichkeit viel größer, dass jedem Fehler, der aus dem Treiber kommt, eine nützliche Aufrufliste zugeordnet ist. Eine Anrufliste, die einem Fehler zugeordnet ist, ermöglicht eine schnelle Diagnose und genaue Dr. Watson-Protokolle.

Sie sollten pfnSetErrorCb in Ihrem Treibercode verwenden, wenn in Ihrem Treiber etwas schief geht, obwohl die Rückgabe eines Fehlercodes, den die Runtime für die jeweilige Treiberfunktion nicht zulässt, von der Runtime als Treiberfehler oder -problem bestimmt wird. Noch schlimmer wäre es für den Benutzermodusanzeigetreiber, kritische Fehler zu absorbieren und weiterzufahren. Der Benutzermodusanzeigetreiber sollte pfnSetErrorCb so nah wie möglich am Punkt der Fehlererkennung aufrufen, um einen nützlichen Aufrufstapel für das Post-Mortem-Debuggen bereitzustellen.

In der folgenden Tabelle sind die Fehlerkategorien aufgeführt, die die Direct3D-Runtime für bestimmte Treiberfunktionen zulässt.

Fehlerkategorie	Bedeutung
NoErrors	Der Treiber sollte keine Fehler auftreten, einschließlich D3DDDIERR_DEVICEREMOVED. Die Runtime bestimmt, dass jeder Aufruf von pfnSetErrorCb kritisch ist.
AllowDeviceRemoved	Für den Treiber sollten keine Fehler auftreten, mit Ausnahme von D3DDDIERR_DEVICEREMOVED. Die Runtime bestimmt, dass jeder Aufruf von pfnSetErrorCb , der D3DDDIERR_DEVICEREMOVED nicht übergibt, kritisch ist. Der Treiber muss DEVICEREMOVED nicht zurückgeben, wenn das Gerät entfernt wurde. Die Runtime ermöglicht es dem Treiber jedoch, DEVICEREMOVED zurückzugeben, falls DEVICEREMOVED die Treiberfunktion beeinträchtigt hat, was normalerweise nicht passieren sollte.
AllowOutOfMemory	Der Treiber kann möglicherweise nicht mehr genügend Arbeitsspeicher haben. Daher kann der Treiber E_OUTOFMEMORY und D3DDDIERR_DEVICEREMOVED über pfnSetErrorCb übergeben. Die Runtime bestimmt, dass alle anderen Fehlercodes kritisch sind.
AllowCounterCreationErrors	Der Treiber kann möglicherweise nicht mehr genügend Arbeitsspeicher haben. Der Treiber kann auch aufgrund der exklusiven Natur von Leistungsindikatoren keine Indikatoren erstellen. Daher kann der Treiber E_OUTOFMEMORY, DXGI_DDI_ERR_NONEXCLUSIVE und D3DDDIERR_DEVICEREMOVED über pfnSetErrorCb übergeben. Die Runtime bestimmt, dass alle anderen Fehlercodes kritisch sind.
AllowMapErrors	Der Treiber sollte auf Ressourcenkonflikte überprüfen. Daher kann der Treiber DXGI_DDI_ERR_WASSTILLDRAWING über pfnSetErrorCb übergeben, wenn das D3D10_DDI_MAP_FLAG_DONOTWAIT-Flag an die ResourceMap-Funktion des Treibers übergeben wurde. Der Treiber kann auch D3DDDIERR_DEVICEREMOVED über pfnSetErrorCb übergeben. Die Runtime bestimmt, dass alle anderen Fehlercodes kritisch sind.
AllowGetDataErrors	Der Treiber sollte überprüfen, ob die Abfrage abgeschlossen ist. Daher kann der Treiber DXGI_DDI_ERR_WASSTILLDRAWING über pfnSetErrorCb übergeben, wenn die Abfrage noch nicht abgeschlossen ist. Der Treiber kann auch D3DDDIERR_DEVICEREMOVED über pfnSetErrorCb übergeben. Die Runtime bestimmt, dass alle anderen Fehlercodes kritisch sind.
AllowWKCheckCounterErrors	Die CheckCounter-Funktion des Treibers sollte angeben, ob sie laufzeitdefinierte Leistungsindikatoren unterstützt. Daher kann der Treiber DXGI_DDI_ERR_UNSUPPORTED über pfnSetErrorCb übergeben. Die Runtime bestimmt, dass alle anderen Fehlercodes kritisch sind. Der Treiber kann keine D3DDDIERR_DEVICEREMOVED für eine Überprüfungstypfunktion zurückgeben.
AllowDDCheckCounterErrors	Der Treiber sollte den geräteabhängigen Zählerbezeichner (Counter-ID) überprüfen, um sicherzustellen, dass sich die Zähler-ID innerhalb des Bereichs befindet und genügend Platz zum Kopieren der einzelnen Zählerzeichenfolgen in den bereitgestellten Puffer vorhanden ist. Der Treiber kann E_INVALIDARG über pfnSetErrorCb übergeben, wenn die Parameter auf diese Weise falsch sind. Der Treiber kann keine D3DDDIERR_DEVICEREMOVED für eine Überprüfungstypfunktion zurückgeben.