Gestione degli errori

Le funzioni Direct3D versione 10 implementate da un driver di visualizzazione in modalità utente in genere hanno VOID per un tipo di parametro restituito. L'eccezione principale di questa regola è la funzione di tipo CalcPrivateObjTypeSize (ad esempio, la funzione CalcPrivateResourceSize ). Questo tipo di funzione restituisce un tipo di parametro SIZE_T che indica le dimensioni dell'area di memoria richiesta dal driver per la creazione del tipo di oggetto specifico tramite la funzione CreateObjType-type (ad esempio , CreateResource(D3D10)).

La restituzione di VOID impedisce al driver di visualizzazione in modalità utente di notificare al runtime Direct3D gli errori nel modo convenzionale, ovvero tramite il parametro restituito della funzione del driver di visualizzazione in modalità utente. Al contrario, il driver di visualizzazione in modalità utente deve usare la funzione di callback pfnSetErrorCb del runtime Direct3D per passare tali informazioni al runtime. Il runtime fornisce un puntatore al relativo pfnSetErrorCb nella struttura D3D10DDI_CORELAYER_DEVICECALLBACKS a cui punta il membro pUMCallbacks della struttura D3D10DDIARG_CREATEDEVICE in una chiamata alla funzione CreateDevice(D3D10).

La pagina di riferimento per ogni funzione driver di visualizzazione in modalità utente specifica gli errori che la funzione può passare attraverso una chiamata a pfnSetErrorCb. Ciò significa che se il driver di visualizzazione in modalità utente chiama pfnSetErrorCb con un codice di errore non consentito per la funzione del driver di visualizzazione in modalità utente corrente, il runtime determina che la condizione di errore è critica e agisce in modo appropriato. Poiché il runtime agisce in modo appropriato durante pfnSetErrorCb, non è consigliabile invertire gli effetti della chiamata a pfnSetErrorCb( E_FAIL ) chiamando qualcosa come pfnSetErrorCb( S_OK ). In realtà, il runtime determina che S_OK non è valido o critico come E_FAIL. Il concetto di codice restituito S_OK equivale alla funzione del driver di visualizzazione in modalità utente che non chiama pfnSetErrorCb .

Se il runtime Direct3D determina che una condizione di errore è critica, verrà prima eseguita registrando l'errore con dr. Watson, ovvero il debugger predefinito post-mortem (JUST-in-time). Il runtime perderà quindi il dispositivo a scopo, simulando così lo scenario di ricezione del codice di errore D3DDDIERR_DEVICEREMOVED. Richiedendo al driver di chiamare la funzione di callback pfnSetErrorCb , le probabilità sono molto maggiori che ogni errore proveniente dal driver avrà uno stack di chiamate utile associato. La presenza di uno stack di chiamate associato a un errore consente la diagnosi rapida e i log accurati di Dr. Watson.

È consigliabile usare pfnSetErrorCb nel codice del driver quando si verifica un errore nel driver anche se viene restituito un codice di errore che il runtime non consente la funzione del driver specifica è determinato dal runtime come bug o problema del driver. Sarebbe ancora peggio per il driver di visualizzazione in modalità utente assorbire gli errori critici e continuare. Il driver di visualizzazione in modalità utente deve chiamare pfnSetErrorCb il più vicino possibile al punto del rilevamento degli errori per fornire uno stack di chiamate utile per il debug post-mortem.

Nella tabella seguente sono elencate le categorie di errori consentiti dal runtime Direct3D da funzioni driver specifiche.

Categoria di errore	Significato
NoErrors	Il driver non deve riscontrare errori, incluso D3DDDIERR_DEVICEREMOVED. Il runtime determinerà che qualsiasi chiamata a pfnSetErrorCb è critica.
AllowDeviceRemoved	Il driver non deve riscontrare errori, ad eccezione di D3DDDIERR_DEVICEREMOVED. Il runtime determinerà che qualsiasi chiamata a pfnSetErrorCb che non passa D3DDDIERR_DEVICEREMOVED è fondamentale. Il driver non è necessario per restituire DEVICEREMOVED se il dispositivo è stato rimosso. Tuttavia, il runtime consente al driver di restituire DEVICEREMOVED, nel caso in cui DEVICEREMOVED interferisca con la funzione driver, che in genere non deve verificarsi.
AllowOutOfMemory	Il driver può esaurire la memoria. Pertanto, il driver può passare E_OUTOFMEMORY e D3DDDIERR_DEVICEREMOVED tramite pfnSetErrorCb. Il runtime determinerà che tutti gli altri codici di errore sono critici.
AllowCounterCreationErrors	Il driver può esaurire la memoria. Il driver potrebbe anche non essere in grado di creare contatori a causa della natura esclusiva dei contatori. Pertanto, il driver può passare E_OUTOFMEMORY, DXGI_DDI_ERR_NONEXCLUSIVE e D3DDDIERR_DEVICEREMOVED tramite pfnSetErrorCb. Il runtime determinerà che tutti gli altri codici di errore sono critici.
AllowMapErrors	Il driver deve verificare la contesa di risorse. Pertanto, il driver può passare DXGI_DDI_ERR_WASSTILLDRAWING tramite pfnSetErrorCb se il flag D3D10_DDI_MAP_FLAG_DONOTWAIT è stato passato alla funzione ResourceMap del driver. Il driver può anche passare D3DDDIERR_DEVICEREMOVED tramite pfnSetErrorCb. Il runtime determinerà che tutti gli altri codici di errore sono critici.
AllowGetDataErrors	Il driver deve verificare il completamento della query. Pertanto, il driver può passare DXGI_DDI_ERR_WASSTILLDRAWING tramite pfnSetErrorCb se la query non è ancora stata completata. Il driver può anche passare D3DDDIERR_DEVICEREMOVED tramite pfnSetErrorCb. Il runtime determinerà che tutti gli altri codici di errore sono critici.
AllowWKCheckCounterErrors	La funzione CheckCounter del driver deve indicare se supporta i contatori definiti dal runtime. Pertanto, il driver può passare DXGI_DDI_ERR_UNSUPPORTED tramite pfnSetErrorCb. Il runtime determinerà che tutti gli altri codici di errore sono critici. Il driver non può restituire D3DDDIERR_DEVICEREMOVED per qualsiasi funzione check-type.
AllowDDCheckCounterErrors	Il driver deve convalidare l'identificatore del contatore dipendente dal dispositivo (ID contatore) per assicurarsi che l'ID contatore sia compreso nell'intervallo e che vi sia spazio sufficiente per copiare ogni stringa del contatore nel buffer fornito. Il driver può passare E_INVALIDARG tramite pfnSetErrorCb, quando i parametri non sono corretti in questo modo. Il driver non può restituire D3DDDIERR_DEVICEREMOVED per qualsiasi funzione check-type.