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

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.

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. The EXR format cannot contain complicated multi-image formats, so the TexMetadata info is redundant information.

auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromEXRFile( L"flowers.exr", nullptr, *image );
if ( FAILED(hr) )
    // error

A EXR file can only store one 2D 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.

Further reading

Kainz, Bogart, and Hess. "Chapter 26. The OpenEXR Image File Format", GPU Gems, Addison-Wesley, 2004 link