CreateTexture

Creates a Direct3D resource from a set of images.

This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using DDSTextureLoader DX11 / DX12, and/or WICTextureLoader DX11 / DX12 instead of DirectXTex.

DirectX 11

HRESULT CreateTexture( ID3D11Device* pDevice,
    const Image* srcImages, size_t nimages, const TexMetadata& metadata,
    ID3D11Resource** ppResource );

HRESULT CreateTextureEx( ID3D11Device* pDevice,
    const Image* srcImages, _In_ size_t nimages, const TexMetadata& metadata,
    D3D11_USAGE usage, unsigned int bindFlags,
    unsigned int cpuAccessFlags, unsigned int miscFlags,
    bool forceSRGB,
    ID3D11Resource** ppResource );

DirectX 12

HRESULT CreateTexture( ID3D12Device* pDevice, const TexMetadata& metadata,
    ID3D12Resource** ppResource );

HRESULT CreateTextureEx( ID3D12Device* pDevice, const TexMetadata& metadata,
    D3D12_RESOURCE_FLAGS resFlags, bool forceSRGB,
    ID3D12Resource** ppResource );

HRESULT PrepareUpload( ID3D12Device* pDevice,
    const Image* srcImages, size_t nimages, const TexMetadata& metadata,
    std::vector<D3D12_SUBRESOURCE_DATA>& subresources );

Parameters

usage: The non-Ex version of this function assumes this is D3D11_USAGE_DEFAULT.
bindFlags: The non-Ex version of this function assumes this is D3D11_BIND_SHADER_RESOURCE.
cpuAccessFlags: The non-Ex version of this function assumes this is 0.
miscFlags: The non-Ex version of this function assumes this is 0.
forceSRGB: This is for working around gamma issues with content that is in the sRGB or similar color space but is not encoded explicitly as an SRGB format.

Example

wchar_t ext[_MAX_EXT];
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );

ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
    hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, nullptr, image );
}
else if ( _wcsicmp( ext, L".tga" ) == 0 )
{
    hr = LoadFromTGAFile( filename, nullptr, image );
}
else if ( _wcsicmp( ext, L".hdr" ) == 0 )
{
    hr = LoadFromHDRFile( filename, nullptr, image );
}
else
{
    hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, nullptr, image );
}
...

DirectX 11

if ( SUCCEEDED(hr) )
{
    ID3D11Resource* pResource = nullptr;
    hr = CreateTexture( device,
        image.GetImages(), image.GetImageCount(),
        image.GetMetadata(), &pResource );
    if ( FAILED(hr) )
        // error!

DirectX 12

if ( SUCCEEDED(hr) )
{
    ID3D12Resource* pResource = nullptr;
    hr = CreateTexture( device, image.GetMetadata(), &pResource );
    if ( FAILED(hr) )
        // error!

    std::vector<D3D12_SUBRESOURCE_DATA> subresources;
    hr = PrepareUpload( device, image.GetImages(), image.GetImageCount(), metadata,
        subresources );
    if ( FAILED(hr) )
        // error!

    // upload is implemented by application developer. Here's one solution using <d3dx12.h>
    const UINT64 uploadBufferSize = GetRequiredIntermediateSize(pResource,
        0, static_cast<unsigned int>(subresources.size()));

    ComPtr<ID3D12Resource> textureUploadHeap;
    hr = device->CreateCommittedResource(
        &CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_UPLOAD),
        D3D12_HEAP_FLAG_NONE,
        &CD3DX12_RESOURCE_DESC::Buffer(uploadBufferSize),
        D3D12_RESOURCE_STATE_GENERIC_READ,
        nullptr,
        IID_PPV_ARGS(textureUploadHeap.GetAddressOf()));
    if (FAILED(hr))
        // error!

    UpdateSubresources(commandList,
        pResource, textureUploadHeap.Get(),
        0, 0, static_cast<unsigned int>(subresources.size()),
        subresources.data());

Remark

This function does not provide support for auto-gen mipmaps (the runtime/engine loaders can support this) because the assumption is if you need mipmaps with DirectTex you will call GenerateMipMaps or GenerateMipMaps3D