Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Ladicí vrstva DirectML je volitelná komponenta pro vývoj, která vám pomůže při ladění kódu DirectML. Pokud je tato možnost povolená, ladicí vrstva DirectML zabalí volání rozhraní DirectML API a poskytne vám další ověření a zprávy jako vývojář. Ladicí vrstva je implementována v samostatné knihovně, DirectML.Debug.dll, která je podmíněně načtena při běhu základní runtime knihovnou DirectML.dll.
Důrazně doporučujeme povolit ladicí vrstvu při vývoji aplikací pomocí DirectML, protože může poskytovat neocenitelné informace v případě neplatného použití rozhraní API.
Přehled zpráv vrstvy ladění
Následující příklad kódu ukazuje, jak může ladicí vrstva pomoct při diagnostice nesprávného použití rozhraní API. Tento kód se pokusí sestavit operaci identity DirectML; takže vstupní a výstupní tensory by měly mít stejný tvar a datový typ. V tomto příkladu ale ilustrujeme chybu ve výstupních parametrech tensoru.
uint32_t sizes[] = { 1 };
DML_BUFFER_TENSOR_DESC inputBufferDesc = {};
inputBufferDesc.DataType = DML_TENSOR_DATA_TYPE_FLOAT32;
inputBufferDesc.DimensionCount = ARRAYSIZE(sizes);
inputBufferDesc.Sizes = sizes;
inputBufferDesc.TotalTensorSizeInBytes = 256;
DML_BUFFER_TENSOR_DESC outputBufferDesc = {};
outputBufferDesc.DataType = DML_TENSOR_DATA_TYPE_FLOAT16; // Invalid: doesn't match input type!
outputBufferDesc.DimensionCount = ARRAYSIZE(sizes);
outputBufferDesc.Sizes = sizes;
outputBufferDesc.TotalTensorSizeInBytes = 256;
DML_TENSOR_DESC inputDesc = { DML_TENSOR_TYPE_BUFFER, &inputBufferDesc };
DML_TENSOR_DESC outputDesc = { DML_TENSOR_TYPE_BUFFER, &outputBufferDesc };
DML_ELEMENT_WISE_IDENTITY_OPERATOR_DESC identityDesc = {};
identityDesc.InputTensor = &inputDesc;
identityDesc.OutputTensor = &outputDesc;
DML_OPERATOR_DESC opDesc = { DML_OPERATOR_ELEMENT_WISE_IDENTITY, &identityDesc };
Microsoft::WRL::ComPtr<IDMLOperator> op;
THROW_IF_FAILED(dmlDevice->CreateOperator(&opDesc, IID_PPV_ARGS(&op)));
Bez vrstvy ladění DirectML se poslední krok pro vytvoření operátoru nezdaří a vrátí E_INVALIDARG (0x80070057). Makro THROW_IF_FAILED (další podrobnosti viz WIL) překládá kód chyby do obecné zprávy "parametr je nesprávný" a vytiskne ho do okna výstupu ladicího programu.
TensorValidator.h(203)\DirectML.dll!00007FF83D25ADC9: (caller: 00007FF83D267523) Exception(1) tid(3b54) 80070057 The parameter is incorrect.
Pokud je ale povolená ladicí vrstva DirectML, zobrazí se další informace, které zpřesní příčinu:
D3D12 ERROR: Mismatched tensor data types. Tensor 'Output' has DataType of DML_TENSOR_DATA_TYPE_FLOAT16, while tensor 'Input' has DataType of DML_TENSOR_DATA_TYPE_FLOAT32. Both tensors are expected to have the same DataType. [ UNKNOWN ERROR #1: STRING_FROM_APPLICATION]
TensorValidator.h(203)\DirectML.Debug.dll!00007FF86DF66ADA: (caller: 00007FF86DF81646) Exception(1) tid(9f34) 80070057 The parameter is incorrect.
Všimněte si, jak rozšířené informace začínají chybou D3D12. Když ladicí vrstva DirectML zjistí problém, vždy dává přednost odesílání chybových zpráv do ID3D12InfoQueue přidruženého k ID3D12Device předané během vytváření zařízení DirectML. Chybové zprávy ve frontě informací mají vždy předponu D3D12 ERROR, jak je znázorněno výše; a jsou také přístupné programátorským způsobem pomocí zpětného volání pro zprávy ladicí vrstvy Direct3D 12 (viz blogový příspěvek „D3D12 Debug Layer Message Callback“).
ID3D12InfoQueue je k dispozici pouze tehdy, když je ladicí vrstva Direct3D 12 povolena pomocí ID3D12Debug::EnableDebugLayer. I když je vždy vhodnější povolit (nebo zakázat) vrstvy ladění Direct3D 12 i DirectML, novější verze DirectML podporují základní ověřování parametrů bez vrstvy ladění Direct3D 12. Pokud vytvoříte zařízení DirectML s DML_CREATE_DEVICE_FLAG_DEBUG, a přitom není povolena ladicí vrstva Direct3D 12, chybové zprávy se místo toho zobrazí pomocí OutputDebugStringA:
[DIRECTML WARNING]: enable the D3D debug layer for enhanced validation with DML_CREATE_DEVICE_FLAG_DEBUG.
[DIRECTML ERROR]: Mismatched tensor data types. Tensor 'Output' has DataType of DML_TENSOR_DATA_TYPE_FLOAT16, while tensor 'Input' has DataType of DML_TENSOR_DATA_TYPE_FLOAT32. Both tensors are expected to have the same DataType.
TensorValidator.h(218)\DirectML.Debug.dll!00007FF820C43AFB: (caller: 00007FF820C01CD1) Exception(1) tid(5df8) 80070057 The parameter is incorrect.
Jak naznačuje zpráva upozornění, je nejlepší povolit ladicí vrstvu Direct3D 12, pokud používáte také ladicí vrstvu DirectML. Některé typy ověřování jsou možné pouze v případech, kdy jsou povoleny obě vrstvy ladění.
Instalace ladicích vrstev DirectML a Direct3D 12 (systémová komponenta)
Při použití DirectML jako systémové komponenty (viz historie verzí DirectML) je ladicí vrstva součástí samostatného balíčku Grafických nástrojů distribuovaných jako funkce na vyžádání (FOD) (viz Funkce na vyžádání). Aby bylo možné používat ladicí vrstvu se systémovou verzí DirectML, musíte do svého systému přidat FOD Graphics Tools. FoD obsahuje také vrstvu ladění Direct3D 12, která je užitečná (ale nevyžaduje) pro ladění aplikací DirectML.
Pokud chcete přidat volitelný balíček FOD grafických nástrojů, spusťte z příkazového řádku PowerShellu správce následující příkaz.
Add-WindowsCapability -Online -Name "Tools.Graphics.DirectX~~~~0.0.1.0"
Případně můžete balíček Grafické nástroje přidat z nastavení systému Windows. Ve Windows 10 22H2 a Windows 11 přejdětena >>volitelných funkcí>Přidat volitelnou funkci a vyhledejte grafické nástroje. Ve verzích starších než Windows 10 22H2 přejděte na> Nastaveníaplikací>a funkce>Volitelné funkce>Přidat volitelnou funkci.
Instalace ladicí vrstvy DirectML (samostatně redistribuovatelný)
Při použití DirectML jako samostatné redistribuovatelné knihovny (viz Microsoft.AI.DirectML) se ladicí vrstva DirectML poskytuje v balíčku spolu s základní knihovnou modulu runtime. Umístěte jak DirectML.Debug.dll, tak DirectML.dll vedle spustitelného souboru vaší aplikace.
Pokud pomocí sady Visual Studio přidáte Microsoft.AI.DirectML jako závislost balíčku NuGet, projekt na stránce konfigurace projektu zobrazí možnosti pro zkopírování nebo přeskočení kopírování základních knihoven runtime a ladicí vrstvy. Ve výchozím nastavení je balíček NuGet DirectML nakonfigurovaný tak, aby vždy zkopíroval obě knihovny DLL do výstupní složky projektu. Pokud se ale vrstva ladění nepoužívá, můžete v buildech vydané verze přeskočit kopírování vrstvy ladění.
Povolení vrstvy ladění Direct3D 12
Ladicí vrstva direct3D 12 (d3d12sdklayers.dll) je nezávislá na vrstvě ladění DirectML (DirectML.Debug.dll): Ladicí vrstva DirectML poskytuje rozšířené ověřování pro použití rozhraní DirectML API a ladicí vrstva Direct3D 12 pokrývá využití rozhraní API Direct3D 12. V praxi je ale nejlepší povolit obě vrstvy ladění při vývoji aplikací DirectML. Ladicí vrstva Direct3D 12 je nainstalována jako součást funkce na vyžádání (FOD) sady nástrojů pro grafiku, jak bylo vysvětleno výše. Příklad aktivace vrstvy ladění Direct3D 12 najdete v tématu ID3D12Debug::EnableDebugLayer .
Důležité
Nejprve musíte povolit vrstvu ladění Direct3D 12. Potom povolte ladicí vrstvu DirectML voláním DMLCreateDevice.
Povolení vrstvy ladění DirectML
Ladicí vrstvu DirectML můžete povolit zadáním DML_CREATE_DEVICE_FLAG_DEBUG při volání DMLCreateDevice.
Jakmile povolíte ladicí vrstvu DirectML, všechny chyby DirectML nebo neplatná volání rozhraní API způsobí, že informace o ladění bude vygenerována jako výstup z ladění. Tady je příklad.
DML_OPERATOR_CONVOLUTION: invalid D3D12_HEAP_TYPE. DirectML requires all bound buffers to be D3D12_HEAP_TYPE_DEFAULT.
Až do DML_FEATURE_LEVEL_5_2 je potřeba povolit vrstvu ladění Direct3D 12, aby bylo možné povolit vrstvu ladění DirectML. V dřívějších verzích DirectML, pokud je příznak DML_CREATE_DEVICE_FLAG_DEBUG zadán v příznaku a ladicí vrstvy nejsou nainstalovány, pak DMLCreateDevice vrátí DXGI_ERROR_SDK_COMPONENT_MISSING. V novějších verzích DirectML se zprávy odesílají do OutputDebugStringA , pokud ID3D12InfoQueue není k dispozici.
Příklad kódu
Následující kód znázorňuje, jak povolit ladicí vrstvy Direct3D 12 a DirectML pouze pro sestavení ladění.
// By default, disable the DirectML debug layer.
DML_CREATE_DEVICE_FLAGS dmlCreateDeviceFlags = DML_CREATE_DEVICE_FLAG_NONE;
#if defined(_DEBUG)
// If the project is in a debug build, then enable the Direct3D 12 debug layer.
// This is optional (starting in DML_FEATURE_LEVEL_5_2) but strongly recommended!
Microsoft::WRL::ComPtr<ID3D12Debug> debugController;
if (SUCCEEDED(D3D12GetDebugInterface(IID_PPV_ARGS(&debugController))))
{
debugController->EnableDebugLayer();
}
// If the project is in a debug build, then enable debugging via DirectML debug layers with this flag.
dmlCreateDeviceFlags |= DML_CREATE_DEVICE_FLAG_DEBUG;
#endif
// Create the DirectML device.
Microsoft::WRL::ComPtr<IDMLDevice> dmlDevice;
THROW_IF_FAILED(DMLCreateDevice(
d3D12Device.Get(),
dmlCreateDeviceFlags,
IID_PPV_ARGS(&dmlDevice));