DirectXErrors
The utility functions in this repository implement FormatMessage-like API for HRESULT codes returned from Microsoft’s graphic APIs.
Motivation
For some of my projects, I still support Windows 7.
Even on Windows 8+, built-in FormatMessage API knows D3D 10, 11, DXGI and WIC codes, but not the rest of them.
Existing Implementations
Microsoft supplies DXERR.LIB and also there’s dxerr.cpp source file but they have problems.
The messages are Unicode i.e. they take more space in the executable file for no reason.
There’re too many messages there, I often don’t need sound and input, again unneeded messages take space in executable.
Also I didn’t like the quality of that code.
That’s why I’ve implemented my own version.
Using the Code
Copy DirectXErrors/DirectXErrors
source folder into your project.
#include "DirectXErrors/DirectXErrors.h"
If you want CString
version, define DXERR_ATL_STRING
macro. Or if you want std::string
version, define DXERR_STD_STRING
macro.
I don’t recommend using getDxErrorStringW
or getDxErrorDescriptionW
functions. If you won’t, the linker will drop Unicode versions of these strings. formatDxMessageW
is fine, it uses ASCII messages under the hood.
Customizing Messages
If you want to customize which errors are included, open DirectXErrors.cpp source file, and comment out some of the defines at the top of the file, after the comment
// Undefine some of these for D3D-related technologies not used by your app.
But keep in mind some libraries and frameworks, both Microsoft’s and third party, may use some of them even if you don't, so you might get these HRESULT codes. For example, WPF is based on DirectX 9.0c therefore it uses D3D9. Likewise, some parts of Media Foundation on some PCs also use D3D9.
Disclaimers
I’ve only built with VS 2015 and 2017, on Windows 10, with 10 and 8.1 SDKs.
Only tested in Win32 desktop apps but it should probably work for all platforms, except Windows 8.0 and 8.1 store apps which don’t support FORMAT_MESSAGE_ALLOCATE_BUFFER
. Should be easy to fix if you need it.
If your apps fails very often, at 1 kilohertz or more, you might implementing hashmap-based cache for these messages, will work slightly faster. But only a bit, modern C++ compilers implement switch
statements quite well, e.g. VS2017 uses binary search.
See also the license.