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.

Categoria do erro	Significado
NoErrors	O driver não deve encontrar erros, incluindo D3DDDIERR_DEVICEREMOVED. O runtime determinará que qualquer chamada para pfnSetErrorCb é crítica.
AllowDeviceRemoved	O driver não deve encontrar erros, exceto por D3DDDIERR_DEVICEREMOVED. O runtime determinará que qualquer chamada para pfnSetErrorCb que não passa D3DDDIERR_DEVICEREMOVED é crítica. O driver não precisará retornar DEVICEREMOVED se o dispositivo tiver sido removido. No entanto, o runtime permite que o driver retorne DEVICEREMOVED, caso DEVICEREMOVED tenha interferido na função de driver, o que normalmente não deve acontecer.
AllowOutOfMemory	O driver pode ficar sem memória. Portanto, o driver pode passar E_OUTOFMEMORY e D3DDDIERR_DEVICEREMOVED por meio de pfnSetErrorCb. O runtime determinará que quaisquer outros códigos de erro são críticos.
AllowCounterCreationErrors	O driver pode ficar sem memória. O driver também pode não conseguir criar contadores devido à natureza exclusiva dos contadores. Portanto, o driver pode passar E_OUTOFMEMORY, DXGI_DDI_ERR_NONEXCLUSIVE e D3DDDIERR_DEVICEREMOVED por meio de pfnSetErrorCb. O runtime determinará que quaisquer outros códigos de erro são críticos.
AllowMapErrors	O driver deve marcar para contenção de recursos. Portanto, o driver poderá passar DXGI_DDI_ERR_WASSTILLDRAWING por meio de pfnSetErrorCb se o sinalizador D3D10_DDI_MAP_FLAG_DONOTWAIT tiver sido passado para a função ResourceMap do driver. O driver também pode passar D3DDDIERR_DEVICEREMOVED por meio de pfnSetErrorCb. O runtime determinará que quaisquer outros códigos de erro são críticos.
AllowGetDataErrors	O driver deve marcar para conclusão da consulta. Portanto, o driver poderá passar DXGI_DDI_ERR_WASSTILLDRAWING por meio de pfnSetErrorCb se a consulta ainda não tiver sido concluída. O driver também pode passar D3DDDIERR_DEVICEREMOVED por meio de pfnSetErrorCb. O runtime determinará que quaisquer outros códigos de erro são críticos.
AllowWKCheckCounterErrors	A função CheckCounter do driver deve indicar se ela dá suporte a contadores definidos por runtime. Portanto, o driver pode passar DXGI_DDI_ERR_UNSUPPORTED por meio de pfnSetErrorCb. O runtime determinará que quaisquer outros códigos de erro são críticos. O driver não pode retornar D3DDDIERR_DEVICEREMOVED para nenhuma função do tipo marcar.
AllowDDCheckCounterErrors	O driver deve validar o identificador do contador dependente do dispositivo (ID do contador) para garantir que a ID do contador esteja dentro do intervalo e haja espaço suficiente para copiar cada cadeia de caracteres de contador para o buffer fornecido. O driver pode passar E_INVALIDARG por meio de pfnSetErrorCb, quando os parâmetros estão incorretos dessa maneira. O driver não pode retornar D3DDDIERR_DEVICEREMOVED para nenhuma função do tipo marcar.