Control de errores

Las funciones de Direct3D versión 10 que implementa un controlador de visualización en modo de usuario suelen tener VOID para un tipo de parámetro devuelto. La excepción principal a esta regla es la función CalcPrivateObjTypeSize-type (por ejemplo, la función CalcPrivateResourceSize ). Este tipo de función devuelve un tipo de parámetro SIZE_T que indica el tamaño de la región de memoria que el controlador necesita para crear el tipo de objeto determinado mediante la función CreateObjType-type (por ejemplo, CreateResource(D3D10)).

Devolver VOID impide que el controlador de pantalla en modo de usuario notifique al tiempo de ejecución de Direct3D errores de la forma convencional (es decir, a través de un parámetro de devolución de función del controlador de pantalla en modo de usuario). En su lugar, el controlador de pantalla en modo de usuario debe usar la función de devolución de llamada pfnSetErrorCb del entorno de ejecución de Direct3D para volver a pasar dicha información al tiempo de ejecución. El runtime proporciona un puntero a su pfnSetErrorCb en la estructura D3D10DDI_CORELAYER_DEVICECALLBACKS que el miembro pUMCallbacks de la estructura D3D10DDIARG_CREATEDEVICE apunta a en una llamada a la función CreateDevice(D3D10).

La página de referencia de cada función de controlador de visualización en modo de usuario especifica los errores que la función puede pasar a través de una llamada a pfnSetErrorCb. Esto significa que si el controlador de pantalla en modo de usuario llama a pfnSetErrorCb con un código de error que no se permite para la función actual del controlador de visualización en modo de usuario, el tiempo de ejecución determina que la condición de error es crítica y actúa correctamente. Dado que el tiempo de ejecución actuará correctamente durante pfnSetErrorCb, no debe esperar que pueda invertir los efectos de llamar a pfnSetErrorCb( E_FAIL ) llamando a algo como pfnSetErrorCb( S_OK ). De hecho, el tiempo de ejecución determina que S_OK es tan no válido o crítico como E_FAIL. El concepto de un código de retorno de S_OK es equivalente a la función de controlador de visualización en modo de usuario que no llama a pfnSetErrorCb en absoluto.

Si el tiempo de ejecución de Direct3D determina que una condición de error es crítica, primero realizará la acción registrando el error con el depurador predeterminado post-mortem (Just-In-Time). A continuación, el tiempo de ejecución perderá el dispositivo a propósito, emulando así el escenario de recepción del código de error D3DDDIERR_DEVICEREMOVED. Al requerir que el controlador llame a la función de devolución de llamada pfnSetErrorCb , las probabilidades son mucho mayores que todos los errores que salen del controlador tendrán una pila de llamadas útil asociada. Tener una pila de llamadas asociada a un error permite un diagnóstico rápido y registros precisos del Dr. Watson.

Debe usar pfnSetErrorCb en el código del controlador cuando algo va mal en el controlador aunque devuelva un código de error que el tiempo de ejecución no permita la función de controlador determinada viene determinada por el tiempo de ejecución como un error o problema del controlador. Sería aún peor que el controlador de pantalla en modo de usuario absorba errores críticos y continúe. El controlador de pantalla en modo de usuario debe llamar a pfnSetErrorCb lo más cerca posible del punto de detección de errores para proporcionar una pila de llamadas útil para la depuración posterior al mortem.

En la tabla siguiente se enumeran las categorías de errores que el tiempo de ejecución de Direct3D permite desde funciones de controlador concretas.

Categoría del error	Significado
NoErrors	El controlador no debe encontrar ningún error, incluida la D3DDDIERR_DEVICEREMOVED. El tiempo de ejecución determinará que cualquier llamada a pfnSetErrorCb es fundamental.
AllowDeviceRemoved	El controlador no debe encontrar ningún error, excepto por D3DDDIERR_DEVICEREMOVED. El tiempo de ejecución determinará que cualquier llamada a pfnSetErrorCb que no pase D3DDDIERR_DEVICEREMOVED sea fundamental. El controlador no es necesario para devolver DEVICEREMOVED si se ha quitado el dispositivo. Sin embargo, el tiempo de ejecución permite al controlador devolver DEVICEREMOVED, en caso de que DEVICEREMOVED interfiera con la función del controlador, lo que normalmente no debería ocurrir.
AllowOutOfMemory	Es posible que el controlador se quedes sin memoria. Por lo tanto, el controlador puede pasar E_OUTOFMEMORY y D3DDDIERR_DEVICEREMOVED a través de pfnSetErrorCb. El tiempo de ejecución determinará que cualquier otro código de error sea crítico.
AllowCounterCreationErrors	Es posible que el controlador se quedes sin memoria. Es posible que el controlador también no pueda crear contadores debido a la naturaleza exclusiva de los contadores. Por lo tanto, el controlador puede pasar E_OUTOFMEMORY, DXGI_DDI_ERR_NONEXCLUSIVE y D3DDDIERR_DEVICEREMOVED a través de pfnSetErrorCb. El tiempo de ejecución determinará que cualquier otro código de error sea crítico.
AllowMapErrors	El controlador debe comprobar la contención de recursos. Por lo tanto, el controlador puede pasar DXGI_DDI_ERR_WASSTILLDRAWING a través de pfnSetErrorCb si la marca de D3D10_DDI_MAP_FLAG_DONOTWAIT se pasó a la función ResourceMap del controlador. El controlador también puede pasar D3DDDIERR_DEVICEREMOVED a través de pfnSetErrorCb. El tiempo de ejecución determinará que cualquier otro código de error sea crítico.
AllowGetDataErrors	El controlador debe comprobar la finalización de la consulta. Por lo tanto, el controlador puede pasar DXGI_DDI_ERR_WASSTILLDRAWING a través de pfnSetErrorCb si la consulta aún no ha finalizado. El controlador también puede pasar D3DDDIERR_DEVICEREMOVED a través de pfnSetErrorCb. El tiempo de ejecución determinará que cualquier otro código de error sea crítico.
AllowWKCheckCounterErrors	La función CheckCounter del controlador debe indicar si admite contadores definidos por el entorno de ejecución. Por lo tanto, el controlador puede pasar DXGI_DDI_ERR_UNSUPPORTED a través de pfnSetErrorCb. El tiempo de ejecución determinará que cualquier otro código de error sea crítico. El controlador no puede devolver D3DDDIERR_DEVICEREMOVED para ninguna función de tipo check.
AllowDDCheckCounterErrors	El controlador debe validar el identificador de contador dependiente del dispositivo (id. de contador) para asegurarse de que el identificador del contador está dentro del intervalo y que hay suficiente espacio para copiar cada cadena de contador en el búfer proporcionado. El controlador puede pasar E_INVALIDARG a través de pfnSetErrorCb, cuando los parámetros son incorrectos de esta manera. El controlador no puede devolver D3DDDIERR_DEVICEREMOVED para ninguna función de tipo check.