Adding OpenEXR

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.

Be sure to note that the OpenEXR library has it's own license terms, as does the required ZLIB library.

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. Save these files to your project directory and add them to the project.

Note if you want to add OpenEXR support directly to your local build of the DirectXTex library, you should edit DirectXTexEXR.cpp and add #include "DirectXTexP.h" to the top of the file. This is required for proper Precompiled Header behavior. You should also comment out the first anonymous namespace as it defines helpers already defined in the DirectXTexP.h header such as safe_handle, ScopedHandle, auto_delete_file, etc.

For the DirectXTexEXR.cpp file, update the project property Additional Include Directories to include the OpenEXR library headers.

If using the recommended scripts above, add .\local\include\OpenEXR

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 2015 / VS 2017 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.

Note that OpenEXR is subject to it's own license as does zlib

Functions

GetMetadataFromEXRFile

Returns the TexMetadata from a .EXR file.

HRESULT GetMetadataFromEXRFile( const 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, and R32G32B32_FLOAT data are supported for writing, and are always written as half 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.