HDR I O Functions

DirectXTex

The Radiance RGBE (.HDR) format is commonly used as a texture source file format in game development for high-dynamic range images, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.

GetMetadataFromHDRMemory, GetMetadataFromHDRFile

Returns the TexMetadata metadata from a .HDR file.

HRESULT GetMetadataFromHDRMemory( const void* pSource, size_t size,
    TexMetadata& metadata );

HRESULT GetMetadataFromHDRFile( const wchar_t* szFile,
    TexMetadata& metadata );

LoadFromHDRMemory, LoadFromHDRFile

Loads a .HDR file.

HRESULT LoadFromHDRMemory( const void* pSource, size_t size,
    TexMetadata* metadata, ScratchImage& image );

HRESULT LoadFromHDRFile( const wchar_t* szFile,
    TexMetadata* metadata, ScratchImage& image );

• The data is always loaded as R32G32B32A32_FLOAT with the alpha channel always set to 1.
• If the file contains a 32-bit_rle_xyze header, no color space conversions are performed and the data is read "as is".

SaveToHDRMemory, SaveToHDRFile

Saves an image to a .HDR file.

HRESULT SaveToHDRMemory( const Image& image, Blob& blob );

HRESULT SaveToHDRFile( const Image& image, const wchar_t* szFile );

• R32G32B32A32_FLOAT, R32G32B32_FLOAT, and R16G16B16A16_FLOAT data are supported for writing. Alpha channel information is ignore when writing the .HDR file.
• Always writes using the 32-bit_rle_rgbe format

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

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

A HDR file can only store one 2D image.

const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToHDRFile( *img, L"NEW_IMAGE.HDR" );
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_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 = SaveToHDRFile( img, L"NEW_IMAGE.HDR" );
if ( FAILED(hr) )
    // error

Implementation Notes

• The reader only supports -Y +X format headers

Windows Store apps

File access and permissions (Windows Runtime apps)

Load

If you wish to load an image from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use LoadFromHDRFile on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).

// Using C++/CX (/ZW) and the Parallel Patterns Library (PPL)
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
    if (file)
    {
        auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
        create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
        {
            if ( tempFile )
            {
                HRESULT hr = LoadFromHDRFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });
}

Save

For SaveToHDRFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:

auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base

If you are going to immediately copy it to another location via StorageFolder, then use the app's temporary folder:

auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base

Further reading

Greg Ward, "Real Pixels", Graphics Gems II, James Arvo (editor), Academic Press, 1991, ISBN: 0120644819, p. 80-83 (code)

High Dynamic Range Image Encodings