Manipulando erros

As funções do Direct3D versão 10 que um driver de exibição no modo de usuário implementa normalmente têm VOID para um tipo de parâmetro de retorno. A principal exceção a essa regra é a função CalcPrivateObjTypeSize-type (por exemplo, a função CalcPrivateResourceSize ). Esse tipo de função retorna um tipo de parâmetro SIZE_T que indica o tamanho da região de memória que o driver requer para criar o tipo de objeto específico por meio da função CreateObjType-type (por exemplo, CreateResource(D3D10)).

Retornar VOID impede que o driver de exibição no modo de usuário notifique o runtime do Direct3D de erros da maneira convencional (ou seja, por meio de um parâmetro de retorno de função do driver de exibição no modo de usuário). Em vez disso, o driver de exibição do modo de usuário deve usar a função de retorno de chamada pfnSetErrorCb do runtime do Direct3D para passar essas informações de volta para o runtime. O runtime fornece um ponteiro para seu pfnSetErrorCb na estrutura D3D10DDI_CORELAYER_DEVICECALLBACKS para a qual o membro pUMCallbacks da estrutura D3D10DDIARG_CREATEDEVICE aponta em uma chamada para a função CreateDevice(D3D10).

A página de referência para cada função de driver de exibição do modo de usuário especifica os erros que a função pode passar por uma chamada para pfnSetErrorCb. Isso significa que, se o driver de exibição do modo de usuário chamar pfnSetErrorCb com um código de erro que não é permitido para a função de driver de exibição do modo de usuário atual, o runtime determinará que a condição de erro é crítica e age adequadamente. Como o runtime agirá adequadamente durante pfnSetErrorCb, você não deve esperar que possa reverter os efeitos de chamar pfnSetErrorCb( E_FAIL ) chamando algo como pfnSetErrorCb( S_OK ). Na verdade, o runtime determina que S_OK é tão inválido ou crítico quanto E_FAIL. O conceito de um código de retorno S_OK é equivalente à função de driver de exibição do modo de usuário que não chama pfnSetErrorCb .

Se o runtime do Direct3D determinar que uma condição de erro é crítica, ele primeiro executará uma ação registrando o erro com o Dr. Watson , o depurador pós-mortem padrão (just-in-time). Em seguida, o runtime perderá o dispositivo de propósito, emulando assim o cenário de recebimento do código de erro D3DDDIERR_DEVICEREMOVED. Ao exigir que o driver chame a função de retorno de chamada pfnSetErrorCb , as chances são muito maiores de que cada erro que sai do driver tenha uma pilha de chamadas útil associada a ela. Ter uma pilha de chamadas associada a um erro permite o diagnóstico rápido e os logs precisos do Dr. Watson.

Você deve usar pfnSetErrorCb em seu código de driver quando algo der errado em seu driver, mesmo retornando um código de erro que o runtime não permite para a função de driver específica é determinado pelo runtime como um bug ou problema de driver. Seria ainda pior para o driver de exibição do modo de usuário absorver erros críticos e continuar. O driver de exibição do modo de usuário deve chamar pfnSetErrorCb o mais próximo possível do ponto da detecção de erros para fornecer uma pilha de chamadas útil para depuração post mortem.

A tabela a seguir lista as categorias de erros que o runtime do Direct3D permite de funções de driver específicas.