Where’s DXERR.LIB?


One of the little utility libraries in the DirectX SDK is a static library for converting HRESULTs to text strings for debugging and diagnostics known as DXERR.LIB. There were once even older versions of this library, DXERR8.LIB and DXERR9.LIB, but they were removed from the DirectX SDK many years back in favor of a unified DXERR.LIB. The DirectX Error Lookup Utility is nothing more than a little front-end UI tool for getting results from DXERR.LIB.

For the Windows SDK 8.0 this library was not brought forward (see “Where is the DirectX SDK?“). This is primarily because HRESULTS for DirectX graphics APIs were added to the FormatMessage function when using FORMAT_MESSAGE_FROM_SYSTEM in Windows 8 which already supports most of the system error codes reported by DXERR. The DirectX SDK version of DXERR.LIB also contained a lot of error codes for legacy components that are no longer relevant to development using the Windows SDK 8.0.

DXERR.LIB contained the following functions (both ASCII and UNICODE):

  • DXGetErrorString
  • DXGetErrorDescription
  • DXTrace

And the macros DXTRACE_MSG, DXTRACE_ERR, DXTRACE_ERR_MSGBOX

If you are still using legacy components like D3DX, DXUT, etc. from the DirectX SDK then you can continue to link to the legacy version of DXERR.LIB as well. For those wanting to get away from dependancies on the DirectX SDK as we’ve recommended, I’ve attached a streamlined version of the library to this post. It only supports UNICODE and I had to change DXGetErrorDescription to copy the result to a buffer rather than return a static string in order to make use of FormatMessage where possible, but otherwise it should serve much the same purpose. You can modify it to suit your needs a well.

Note: The FormatMessage flag FORMAT_MESSAGE_ALLOCATE_BUFFER is not supported for Windows Store apps because it makes use of LocalAlloc.

The source code for this package is bound to the Microsoft Public License (Ms-PL).

While we are on the topic of utility libraries, the DXGUID.LIB static library is also present in the Windows SDK 8.0 with the Direct3D 11.1, Direct2D, DirectWrite, and WIC GUIDs added; and the XACT and XAUDIO2 GUIDs removed. There’s nothing particular special about DXGUID.LIB because you could easily define the GUIDs using #define INITGUID before including the relevant headers in one (and only one) module of your program yourself, but it is very convenient not to have to do that.

Update: in DXTraceW now takes __FILEW__ along with some /analyze and /W4 cleanup, support for WINAPI_FAMILY macros; define NOMINMAX; some fixes for VS 2015 printf string portability, package updated on November 9, 2015.

DXUT: This DXERR is included in the DXUT for Win32 Desktop Update

VS 2015: The VS 2015 C Runtime is not compatible with the DXERR.LIB that ships in the legacy DirectX SDK. You will get link errors trying to use it. You can use this module to replace DXERR LIB by will have to rebuild the code that uses it.

dxerr_nov2015.zip

Comments (18)

  1. キキジキ says:

    Nice, thanks.

  2. Kevin says:

    What happens when someone with Windows Vista, for example, runs your code? Their version of their OS won't have the directx error codes for DirectX?

  3. If you look at the code for DXGetErrorDescriptionW, you see it falls back to a bunch of built-in translations if the FormatMessageW fails to recognize the error.

  4. Kevin says:

    Oh, ok. Why deprecate dxerr when you now need to use a third-party library to get error messages now :/

  5. @Kevin – DXERR in particular was not deprecated. The whole DirectX SDK was deprecated in favor of the Windows SDK, and the 'in box' solution for error to message translation is to use FormatMessage as described here. If you use Windows 8 and avoid legacy APIs, you never need to use DXERR. The DXERR in the blog post is a shared source solution to fill the gap for down-level OSes, legacy APIs, etc.

  6. Jon Lennox says:

    This doesn't work — as written — on the v110_xp or v120_xp toolsets, because version 7.1A of the Windows SDK doesn't include d3d11_1.h (even though it does include other Direct X headers and libraries).

    What's the right preprocessor symbol to use to distinguish this case?

  7. @Jon: You could use _WIN32_WINNT, assuming you explicitly set _WIN32_WINNT to 0x0501 as part of your project settings.

    #if (_WIN32_WINNT  >= 0x0600)

    #include <d3d11_1.h>

    #endif

  8. Nikita Black says:

    I'm trying to get error description but without any luck. On win7 with vs2013 I have a nice error message in console. Is there any way to obtain the same description? I've asked on gamedev.net – there's a more detailed description. http://www.gamedev.net/…/662849-get-error-description-from-hresult

  9. @Nikita – the "better" output you are seeing is from the DXGI debug device which is intended for developers to get better diagnostics during development, not for 'friendly output' for a user in a released product. The HRESULT is still a generic error that has a fairly generic description. The whole point of the Direct2D, Direct3D, and DXGI debug device layer is to provide more detailed information when you get something that's not specific as an HRESULT at runtime during development because you can actually fix it. A user cannot do anything about a component in your code getting an "INVALIDCALL" error.

  10. Volgogradetzzz says:

    Thank you, Chuck. As I understood, I need to work with debug layer if I want to get output like in vs console.

  11. Bakwards compatible... says:

    So, it is OK to break DirectX applications that rely on DirectX libraries, but we still have to define NOMINMAX in every single application…

    Do you see the problem here?

    Not that I do not appreciate the effort. You are trying to provide a solution. But if there is one thing the bloody MIN MAX macros taught us is that this blog post should not exist! Are we going to keep retro-compatibility only for the worst parts of the SDKs?

  12. The DXERR implementation shouldn't care about NOMINMAX or not, so I assume the problem is that dxerr.h is pulling in windows.h and not setting NOMINMAX for your application?  For the CodePlex projects, I have adopted a pattern of "#ifndef NOMINMAX #define NOMINMAX #endif" in the public headers. Fundamentally the problem with the <windows.h> min/max macros conflicting with C++11 <algorithm> is not the fault of the DirectX SDK. It's a decision made a long time ago in the Windows platform headers (see KB143208).

  13. Frank Heimes says:

    FormatMessage does NOT support D3D errors! In Visual Studio 2013, Intellisense shows a popup with the detailed message "The device does not support a specified texture-blending argument for the alpha channel." if hovering on the symbol D3DERR_UNSUPPORTEDALPHAARG. Where the heck does it get that string from? FormatMessage works for E_FAIL and the like but yields no string for D3DERR* errors. It's so frustrating. The proper error message does exist but my code is not allowed to query it!

  14. What version of Windows are you running?

  15. Frank Heimes says:

    Windows 8.1 Pro, Visual Studio Premium 2013, Version 12.0.31101.00 Update 4

  16. FormatMessage supports the Direct3D 11, DXGI, etc. errors in winerror.h on Windows 8. For other APIs that are missing, the DXERR implementation in this blog post should help. I found some bugs and updated the package today, so try it out.

  17. Frank Heimes says:

    @Chuck Walbourn Thanks for the prompt service! But I still wonder where Visual Studio finds the elaborate error strings, like "The device does not support a specified texture-blending argument for the alpha channel.". I doubt that these are hard-coded into Visual Studio.