DirectXTex |
---|
The OpenEXR format is a high dynamic-range (HDR) image file format developed by Industrial Light & Magic for use in computer imaging applications. It is commonly used as a source format for HDR textures.
Building the OpenEXR auxiliary library
The OpenEXR library can be obtained from GitHub. Building the library requires CMake and ZLib.
To build the library with Visual C++ 2015 for x64, the zlib.cmd script followed by the openexr.cmd script can be used. Be sure to have installed the Git for Windows tools (optional feature of Visual Studio) before running as well.
The DirectXTex auxiliary module for loading EXR
files is in the DirectXTexEXR.h and DirectXTexEXR.cpp source files. They are included in the Auxiliary
folder of the library distribution.
For the executables that build with this support, you need to update the project property Additional Library Directories to include the OpenEXR libraries.
If using the recommended scripts above, add
.\local\lib
Using NuGet
Rather than building the libraries yourself, you can obtain a version compatible with VS 2019 via the NuGet package manager:
The OpenEXR package x86 or x64 can be used to build DirectXTexEXR.h / DirectXTexEXR.cpp, and then is needed to link the project EXE along with Zlib x86 or x64.
Slightly older VS 2015 packages are also available: OpenEXR x86 / x64; Zlib x86 / x64.
Using vcpkg
OpenEXR support is supported as an opt-in feature for the vcpkg C++ package manager directxtex port.
vcpkg install directxtex[openexr,tools]
License
Note that OpenEXR is subject to its own license as is zlib.
Functions
GetMetadataFromEXRFile
Returns the TexMetadata from a .EXR
file.
HRESULT GetMetadataFromEXRFile( wchar_t* szFile, TexMetadata& metadata );
LoadFromEXRFile
Loads a .EXR
file.
HRESULT LoadFromEXRFile( const wchar_t* szFile, TexMetadata* metadata, ScratchImage& image );
- The data is always loaded as
R16G16B16A16_FLOAT
.
SaveToEXRFile
Saves a single image to a .EXR
file.
HRESULT SaveToEXRFile( const Image& image, const wchar_t* szFile );
R16G16B16A16_FLOAT
,R32G32B32A32_FLOAT
, andR32G32B32_FLOAT
data are supported for writing, and are always written ashalf
channel format data.
Parameters
For the load functions, the metadata parameter can be nullptr as this information is also available in the returned ScratchImage.
Examples
This is a simple loading example.
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromEXRFile( L"flowers.exr", nullptr, *image );
if ( FAILED(hr) )
// error
Storing an image.
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToEXRFile( *img, L"NEW_IMAGE.EXR" );
if ( FAILED(hr) )
// error
You can also save data directly from memory without using the intermediate ScratchImage at all. This example assumes a single 2D image is being written out.
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /* DXGI_FORMAT_R16G16B16A16_FLOAT,
DXGI_FORMAT_R32G32B32A32_FLOAT
or DXGI_FORMAT_R32G32B32_FLOAT */;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToEXRFile( img, L"NEW_IMAGE.EXR" );
if ( FAILED(hr) )
// error
Samples
Sample images can be obtained from GitHub.
Tools
The tools that use DirectXTex can be updated to opt-in to OpenEXR support as well, typically by enabling #define USE_OPENEXR
and rebuilding. See texconv, texdiag, texassemble, and uvatlastool.
Further reading
Kainz, Bogart, and Hess. "Chapter 26. The OpenEXR Image File Format", GPU Gems, Addison-Wesley, 2004 link
For Use
- Universal Windows Platform apps
- Windows desktop apps
- Windows 11
- Windows 10
- Windows 8.1
- Windows 7 Service Pack 1
- Xbox One
- Xbox Series X|S
- Windows Subsystem for Linux
Architecture
- x86
- x64
- ARM64
For Development
- Visual Studio 2022
- Visual Studio 2019 (16.11)
- clang/LLVM v12 - v18
- GCC 10.5, 11.4, 12.3
- MinGW 12.2, 13.2
- CMake 3.20
Related Projects
DirectX Tool Kit for DirectX 11
DirectX Tool Kit for DirectX 12
Tools
See also
All content and source code for this package are subject to the terms of the MIT License.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.