mirror of https://github.com/microsoft/DirectXTex synced 2024-11-21 12:00:06 +00:00

Table of Contents

Building the OpenEXR auxiliary library

Using NuGet
Using vcpkg
License

Functions

GetMetadataFromEXRFile
LoadFromEXRFile
SaveToEXRFile
Parameters
Examples

Samples
Tools
Further reading

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.