-
Notifications
You must be signed in to change notification settings - Fork 437
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.
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 );
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 );
-
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
, andCREATETEX_IGNORE_SRGB
.
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 );
}
...
if ( SUCCEEDED(hr) )
{
ID3D11Resource* pResource = nullptr;
hr = CreateTexture( device,
image.GetImages(), image.GetImageCount(),
image.GetMetadata(), &pResource );
if ( FAILED(hr) )
// error!
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 ad3dx12_x.h
header.
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.
All content and source code for this package are subject to the terms of the MIT License.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
- 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
- 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
DirectX Tool Kit for DirectX 11