Ler em inglês

Compartilhar via


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.