CreateTexture

DirectXTex

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,
    CREATETEX_FLAGS flags,
    ID3D11Resource** ppResource );

DirectX 12

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

HRESULT CreateTextureEx(
    ID3D12Device* pDevice, const TexMetadata& metadata,
    D3D12_RESOURCE_FLAGS resFlags, CREATETEX_FLAGS flags,
    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.

• loadFlags: Values here are CREATETEX_DEFAULT, CREATETEX_FORCE_SRGB, and CREATETEX_IGNORE_SRGB.

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());

Note the data is copied out of the image into the UPLOAD resource by the time the UpdateSubresources returns. The upload resource itself needs to remain live until after the command-list is processed, and the texture won't be ready to use until then.

Typically you'd add a resource barrier on the command-list for the DEFAULT resource to transition it from the initial D3D12_RESOURCE_STATE_COPY_DEST state to something like D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE for rendering so that when the command-list completes, the texture is ready to use.

You can obtain the d3dx12.h header from GitHub. It's included in a number of DirectX 12 templates. For Xbox One, the XDK includes a d3dx12_x.h header.

Remark

The CREATETEX_SRGB flag provides an option 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. This will force the resource format be one of the of DXGI_FORMAT_*_SRGB formats if it exist. Note that no pixel data conversion takes place. The CREATETEX_IGNORE_SRGB flag does the opposite; it will force the resource format to not have the _*_SRGB version.

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

If support for DirectX 12 is required, you must explicitly include #include <d3d12.h> before including #include "DirectXTex.h"

DirectX 12 version does not support creating textures from depth/stencil non-planar data.