mirror of https://github.com/microsoft/DirectXTex synced 2024-11-08 14:00:05 +00:00

Table of Contents

GetMetadataFromHDRMemory, GetMetadataFromHDRFile
LoadFromHDRMemory, LoadFromHDRFile
SaveToHDRMemory, SaveToHDRFile
Parameters
Examples
Implementation Notes
Windows Store apps

Load
Save

Further reading

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

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

DirectXTex Rust bindings

DirectX Tool Kit for DirectX 11

DirectX Tool Kit for DirectX 12

DirectXMesh

DirectXMath

Tools

Test Suite

Content Exporter

DxCapsViewer