Skip to content

Adding OpenEXR

Chuck Walbourn edited this page Jan 20, 2024 · 35 revisions
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, 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.

Further reading

OpenEXR

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

High Dynamic Range Image Encodings

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

DirectXTex Rust bindings

DirectX Tool Kit for DirectX 11

DirectX Tool Kit for DirectX 12

DirectXMesh

DirectXMath

Tools

Test Suite

Content Exporter

DxCapsViewer

See also

DirectX Landing Page

Clone this wiki locally