使用 DXC.exe 與 dxcompiler .dll 介面 - XBOX Game Development Documentation

DXC 支援命令列介面 (dxc.exe) 與 .dll 介面 (dxcompiler.dll、dxcompiler.lib、dxcapi.h 與 d3d12shader.h)。

編譯器二進位檔
DXC 命令列介面
著色器雜湊
反映
PDBs
DXCompiler DLL 介面
使用自訂配置器
XBOX DLL 介面延伸

編譯器二進位檔

對於 Windows，可以從 GitHub 下載最新的編譯器二進位檔。建議您一律更新至最新版本。對於 XBOX，二進位檔會隨 Microsoft Game Development Kit (GDK) 一起安裝，且版本與每個發行版本對應。請注意，對於 .dll 與標頭，XBOX One 使用 “_x” 命名慣例，XBOX Series X|S 使用 “_xs” 命名慣例。 Windows

dxc_<version>\dxc.exe
dxc_<version>\dxcompiler.dll
dxc_<version>\dxcapi.h
dxc_<version>\d3d12shader.h
dxc_<version>\dxcompiler.lib

XBOX One PC 工具

Microsoft GDK\<Version>\GXDK\bin\XboxOne\dxc.exe
Microsoft GDK\<Version>\GXDK\bin\XboxOne\dxcompiler_x.dll
Microsoft GDK\<Version>\GXDK\toolKit\Include\XboxOne\dxcapi_x.h
Microsoft GDK\<Version>\GXDK\toolKit\Include\XboxOne\d3d12shader_x.h
Microsoft GDK\<Version>\GXDK\toolKit\lib\amd64\XboxOne\dxcompiler_x.lib

XBOX One 主機執行階段

Microsoft GDK\<Version>\GXDK\gameKit\Include\XboxOne\dxcapi_x.h
Microsoft GDK\<Version>\GXDK\gameKit\Include\XboxOne\d3d12shader_x.h
Microsoft GDK\<Version>\GXDK\gameKit\lib\amd64\XboxOne\dxcompiler_x.lib

XBOX Series X|S PC 工具

Microsoft GDK\<Version>\GXDK\bin\Scarlett\dxc.exe
Microsoft GDK\<Version>\GXDK\bin\Scarlett\dxcompiler_xs.dll
Microsoft GDK\<Version>\GXDK\toolKit\Include\Scarlett\dxcapi_xs.h
Microsoft GDK\<Version>\GXDK\toolKit\Include\Scarlett\d3d12shader_xs.h
Microsoft GDK\<Version>\GXDK\toolKit\lib\amd64\Scarlett\dxcompiler_xs.lib

XBOX Series X|S 主機執行階段

Microsoft GDK\<Version>\GXDK\gameKit\Include\Scarlett\dxcapi_xs.h
Microsoft GDK\<Version>\GXDK\gameKit\Include\Scarlett\d3d12shader_xs.h
Microsoft GDK\<Version>\GXDK\gameKit\lib\amd64\Scarlett\dxcompiler_xs.lib

不支援使用針對特定平台設計與測試的編譯器，為另一個平台編譯著色器。

DXC 命令列介面

執行 dxc.exe -? 即可取得命令列旗標的完整清單。如果您熟悉 FXC，許多命令列引數都是相同的。以下是一些常見的旗標。

-D <value>              Define macro.
-E <value>              Entry point name.
-Fd <file>              Write debug information to the specified file or directory; trail \ to autogenerate.
-Fo <file>              Output object file.
-Gec                    Enable backward compatibility mode.
-HV <value>             HLSL version (2016, 2017, 2018). Default is 2018.
-Od                     Disable optimizations.
-T <profile>            Set target profile.
    <profile>: ps_6_0, ps_6_1, ps_6_2, ps_6_3, ps_6_4,
                vs_6_0, vs_6_1, vs_6_2, vs_6_3, vs_6_4,
                cs_6_0, cs_6_1, cs_6_2, cs_6_3, cs_6_4,
                gs_6_0, gs_6_1, gs_6_2, gs_6_3, gs_6_4,
                ds_6_0, ds_6_1, ds_6_2, ds_6_3, ds_6_4,
                hs_6_0, hs_6_1, hs_6_2, hs_6_3, hs_6_4,
                lib_6_3, lib_6_4
-Vd                     Disable validation.
-Zi                     Enable debug information.
-Zpc                    Pack matrices in column-major order.
-Zpr                    Pack matrices in row-major order.

DXC 已更新為預設不再將 .pdb (程式資料庫/偵錯資訊) 內嵌在著色器中。根據預設，.pdb 是外部的。

dxc.exe -? 也會回報其編譯器變體：“HLSL Compiler for Windows”、“HLSL Compiler for XBOX One” 或 “HLSL Compiler for XBOX Series X|S”。以下是使用命令列介面的範例。

dxc -E main -T ps_6_0 -Fo myshader.bin -Zi -Fd myshader.pdb -D MYDEFINE=1 myshader.hlsl

在此範例中，myshader.hlsl 會編譯為著色器模型 6.0 像素著色器。編譯後的著色器會依 -Fo 旗標的指定寫入 myshader.bin。偵錯資訊以 -Zi 旗標啟用，.pdb 則以 -Fd 旗標寫出至 myshader.pdb。如果您希望編譯器自動產生 .pdb 名稱，可以提供 .\ 作為 -Fd 引數。同樣地，PDB 中的偵錯資訊不會內嵌在著色器中。此外，在 XBOX 上，必須提供根簽章才能預先編譯著色器。

著色器雜湊

可以使用 -Fsh 命令列旗標將著色器的雜湊儲存至檔案。透過 .dll 介面，一律可以使用 IDxcResult::GetOutput 取得。在 Windows 上，會對著色器 DXIL 進行雜湊以決定其值。在 XBOX 上，雜湊取決於所要求的編譯類型。

如果停用預先編譯，雜湊是針對著色器 DXIL。
如果啟用預先編譯，雜湊是針對預先編譯的著色器。

對於預先編譯的著色器，雜湊會因是否移除 DXIL 而不同，因為包含 DXIL 的著色器支援執行階段編譯 (如有需要)，但已移除 DXIL 的著色器則不支援。

反映

根據預設，反映資料會儲存在著色器中。可以使用 -Qstrip_reflect 旗標將其移除。現在可以使用 -Fre 旗標將反映資料儲存至個別檔案，即使使用了 -Qstrip_reflect 也會儲存該檔案。同樣地，即使使用了 -Qstrip_reflect，也可以使用 IDxcResult::GetOutput 取得個別的反映 Blob。IDxcUtils::CreateReflection 可以從這些個別的反映 Blob 建立反映介面。

PDBs

編譯著色器時，.pdb 檔案名稱 (以 -Fd 選項提供) 與著色器的雜湊會儲存在著色器中。PIX 會使用此資訊尋找著色器 .pdb。在 XBOX 上，如果您將著色器序列化，則只會保留著色器雜湊。在此情況下，最好使用 -Fd .\ 選項，以著色器雜湊作為 .pdb 名稱，讓 PIX 可以輕鬆找到您的 pdb。如果基於某些原因您需要載入不同名稱的 .pdb，可以在 PIX 中手動載入 .pdb。

精簡 .pdb

新的編譯旗標 “-Zs” 會建立一種新類型的 .pdb，比傳統 .pdb 小得多，並可縮短產生 .pdb 時的編譯時間。這些「精簡」.pdb 只包含用於產生著色器的原始程式碼與編譯引數。偵錯著色器時，PIX 會「隨需」產生所需的其他偵錯資訊。請注意，完整的 .pdb (包含精簡 .pdb 的所有內容，以及偵錯工具所使用的完整偵錯資訊) 仍可透過 “-Zi” 旗標支援。

關於編譯器版本的注意事項。

產生 .pdb 時，編譯器的版本會儲存在 .pdb 中，讓 PIX 能夠知道最初編譯著色器時使用的是哪個編譯器。如果與 PIX 相關聯的目前編譯器與用於產生著色器的編譯器不相符，PIX 會回報，如有需要也可以提供相符的編譯器。

新的 pdb 介面。

dxcapi.h 中引進了一個名為 IDxcPdbUtils 的新介面。此介面可讓您檢查原始程式碼、編譯引數、編譯器版本與雜湊，也可讓您視需要從 pdb 重新編譯著色器。

光線追蹤的 .pdb (預覽)

現已啟用對光線追蹤的有限 .pdb 支援。若要使用此功能，請使用 -Zi -Qembed_debug 旗標編譯光線追蹤程式庫。無論是 PC 端的離線 RTPSO 建立或執行階段 RTPSO 建立，都請使用新的呼叫 ID3D12Device8::SetCompileTimeShaderPdbPathX 指定 PDB 位置。如果設定了此路徑，驅動程式會儲存與每個 RTPSO 相關聯的 .pdb 檔案。PIX 接著就可以載入並使用產生的 .pdb。或者，也可以使用 -Zs -Fd 旗標產生精簡的光線追蹤 .pdb，並將其儲存至個別的 .pdb 檔案，而不是內嵌在著色器中。目前建立光線追蹤狀態物件 .pdb 時，仍需使用 ID3D12Device8::SetCompileTimeShaderPdbPathX API。PIX 將能夠使用 RTPSO 的多個程式庫 .pdb 來顯示所有著色器原始程式碼。如需詳細資訊，請參閱 PIX 中的著色器 PDB 文件。

DXCompiler DLL 介面

下列資訊適用於 Windows、XBOX One 與 XBOX Series X|S 編譯器變體。如果不需要，我們將省略 “_x” 與 “_xs” 的任何提及，但資訊仍適用於所有三個平台。若要使用 .dll 介面，請包含 dxcapi.h 與 d3d12shader.h，並連結至 dxcompiler.lib 程式庫或直接載入 dxcompiler.dll。

不支援手動載入與卸載編譯器所需的其他 .dll。建議您在程式的整個生命週期內保持 .dll 載入，而不是在每次編譯著色器時載入與卸載它。

載入編譯器 .dll 之後，呼叫 DxcCreateInstance 以建立各種編譯器介面。

對 DxcCreateInstance 的呼叫是安全執行緒的，但由 DxcCreateInstance 建立的物件不是安全執行緒的。編譯器物件應在同一個執行緒上建立並使用。

跨平台編譯

如果您選擇建立一個可為多個平台編譯的可執行檔，則無法連結任何 dxcompiler 程式庫。您需要直接載入個別的 .dll，並取得各自 DxcCreateInstance 函式的處理序位址。為某個編譯器平台目標建立的物件，無法以任何方式與為另一個編譯器平台目標建立的物件搭配使用。可以使用 “_xs” 標頭，但並非所有功能都在三個平台上完全受支援。此外，必須小心確保 dxcompiler.dll 所載入的 .dll 能被正確處理。

SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_DEFAULT_DIRS);

const WCHAR* szWindowCompilerPath =   L"C:\\LatestDxcCompiler";
const WCHAR* szXboxCompilerPath =     L"C:\\Program Files (x86)\\Microsoft GDK\\191100\\GXDK\\bin\\XboxOne";
const WCHAR* szScarlettCompilerPath = L"C:\\Program Files (x86)\\Microsoft GDK\\191100\\GXDK\\bin\\Scarlett";

// Make sure .dll dependencies are handled correctly.
AddDllDirectory(szWindowCompilerPath);
AddDllDirectory(szXboxCompilerPath);
AddDllDirectory(szScarlettCompilerPath);

// Load the .dlls.
HMODULE hModuleDxcWindows = LoadLibraryEx(L"dxcompiler.dll", NULL, 0);
HMODULE hModuleDxcXbox = LoadLibraryEx(L"dxcompiler_x.dll", NULL, 0);
HMODULE hModuleDxcScarlett = LoadLibraryEx(L"dxcompiler_xs.dll", NULL, 0);

// Get the create interface functions for each platform.
decltype(&DxcCreateInstance) m_pfnDxcCreateInstanceWindows = (decltype(&DxcCreateInstance))GetProcAddress(hModuleDxcWindows, "DxcCreateInstance");
decltype(&DxcCreateInstance) m_pfnDxcCreateInstanceXbox = (decltype(&DxcCreateInstance))GetProcAddress(hModuleDxcXbox, "DxcCreateInstance");
decltype(&DxcCreateInstance) m_pfnDxcCreateInstanceScarlett = (decltype(&DxcCreateInstance))GetProcAddress(hModuleDxcScarlett, "DxcCreateInstance");

使用編譯器介面

建議您使用最新的 IDxcCompiler3 介面，以利用最新的功能，包括指定更多引數的能力。例如，與命令列相同的引數、具名 Blob，以及直接存取著色器雜湊。如果您是從 IDxcCompiler2 移植，且偏好類似 IDxcCompiler::Compile 或 IDxcCompiler2::CompileWithDebug 的介面，可以使用 IDxcUtils::BuildArguments。雖然 IDxcCompiler3::Compile 介面類似命令列介面，但引數是以個別字串傳遞。此外，命令列中用於將含空格的引數組成單一引數的引號可以省略，也不需要特殊命令列字元所需的逸出序列。

命令列	不正確的 IDxcCompiler3::Compile 引數字串	正確的 IDxcCompiler3::Compile 引數字串
-E main	L”-E main”	L”-E”, L”main”
-Fd “my filename with spaces.pdb”	L”-Fd”, L""my filename with spaces.pdb""	L”-Fd”, L”my filename with spaces.pdb”
this^&that”	L”this^&that”	L”this&that”
-D MY_CONSTANT=2.2	L”-D MY_CONSTANT=2.2”	L”-D”, L”MY_CONSTANT=2.2”
-D “MY_CODE= 2 + 2”	L”-D “MY_CODE= 2 + 2""	L”-D”, L”MY_CODE= 2 + 2”
-D __XBOX_DX12_ROOT_SIGNATURE=""CBV(b0), CBV(b1)""	L”-D __XBOX_DX12_ROOT_SIGNATURE=“CBV(b0), CBV(b1)""	L”-D”, L”__XBOX_DX12_ROOT_SIGNATURE=“CBV(b0), CBV(b1)""

下列範例程式碼使用此介面編譯 myshader.hlsl，同時產生 .pdb。一般流程是呼叫 IDxcCompiler3::Compile，然後檢查 IDxcResult 中的錯誤緩衝區、編譯後的著色器、.pdb 與著色器雜湊。

必須使用 -Fd 引數將 .pdb 名稱傳入 Compile 函式。與命令列相同，可以使用 -Fd .\ 讓編譯器自動產生 PDB 名稱。如果 PDB 名稱是自動產生的，您必須使用此名稱儲存 .pdb 檔案，PIX 才能找到它。

在下列範例中，為了簡潔起見已省略常見的錯誤檢查。

#include <atlbase.h>        // Common COM helpers.
#include <dxcapi_x.h>       // Be sure to link with dxcompiler_x.lib.
#include <d3d12shader_x.h>  // Shader reflection.

int main()
{
    // 
    // Create compiler and utils.
    //
    CComPtr<IDxcUtils> pUtils;
    CComPtr<IDxcCompiler3> pCompiler;
    DxcCreateInstance(CLSID_DxcUtils, IID_PPV_ARGS(&pUtils));
    DxcCreateInstance(CLSID_DxcCompiler, IID_PPV_ARGS(&pCompiler));

    //
    // Create default include handler. (You can create your own...)
    //
    CComPtr<IDxcIncludeHandler> pIncludeHandler;
    pUtils->CreateDefaultIncludeHandler(&pIncludeHandler);


    //
    // COMMAND LINE: dxc myshader.hlsl -E main -T ps_6_0 -Zs -D MYDEFINE=1 -Fo myshader.bin -Fd myshader.pdb -D __XBOX_STRIP_DXIL -Qstrip_reflect
    //
   LPCWSTR pszArgs[] =
    {
        L"myshader.hlsl",            // Optional shader source file name for error reporting and for PIX shader source view.  
        L"-E", L"main",              // Entry point.
        L"-T", L"ps_6_0",            // Target.
        L"-Zs",                      // Enable smaller debug information.
        L"-D", L"MYDEFINE=1",        // A single define.
        L"-Fo", L"myshader.bin",     // Optional. Stored in the pdb. 
        L"-Fd", L"myshader.pdb",     // The file name of the pdb. This must either be supplied or the autogenerated file name must be used.
        L"-D", L"__XBOX_STRIP_DXIL", // Strip DXIL.
        L"-Qstrip_reflect",          // Strip reflection into a separate blob. 
    };


    //
    // Open source file.  
    //
    CComPtr<IDxcBlobEncoding> pSource = nullptr;
    pUtils->LoadFile(L"myshader.hlsl", nullptr, &pSource);
    DxcBuffer Source;
    Source.Ptr = pSource->GetBufferPointer();
    Source.Size = pSource->GetBufferSize();
    Source.Encoding = DXC_CP_ACP; // Assume BOM says UTF8 or UTF16 or this is ANSI text.


    //
    // Compile it with specified arguments.
    //
    CComPtr<IDxcResult> pResults;
    pCompiler->Compile(
        &Source,                // Source buffer.
        pszArgs,                // Array of pointers to arguments.
        _countof(pszArgs),      // Number of arguments.
        pIncludeHandler,        // User-provided interface to handle #include directives (optional).
        IID_PPV_ARGS(&pResults) // Compiler output status, buffer, and errors.
    );

    //
    // Print errors if present.
    //
    CComPtr<IDxcBlobUtf8> pErrors = nullptr;
    pResults->GetOutput(DXC_OUT_ERRORS, IID_PPV_ARGS(&pErrors), nullptr);
    // Note that d3dcompiler would return null if no errors or warnings are present.  
    // IDxcCompiler3::Compile will always return an error buffer, but its length will be zero if there are no warnings or errors.
    if (pErrors != nullptr && pErrors->GetStringLength() != 0)
        wprintf(L"Warnings and Errors:\n%S\n", pErrors->GetStringPointer());

    //
    // Quit if the compilation failed.
    //
    HRESULT hrStatus;
    pResults->GetStatus(&hrStatus);
    if (FAILED(hrStatus))
    {
        wprintf(L"Compilation Failed\n");
        return 1;
    }

    //
    // Save shader binary.
    //
    CComPtr<IDxcBlob> pShader = nullptr;
    CComPtr<IDxcBlobUtf16> pShaderName = nullptr;
    pResults->GetOutput(DXC_OUT_OBJECT, IID_PPV_ARGS(&pShader), &pShaderName);
    if (pShader != nullptr)
    {
        FILE* fp = NULL;

        _wfopen_s(&fp, pShaderName->GetStringPointer(), L"wb");
        fwrite(pShader->GetBufferPointer(), pShader->GetBufferSize(), 1, fp);
        fclose(fp);
    }

    //
    // Save pdb.
    //
    CComPtr<IDxcBlob> pPDB = nullptr;
    CComPtr<IDxcBlobUtf16> pPDBName = nullptr;
    pResults->GetOutput(DXC_OUT_PDB, IID_PPV_ARGS(&pPDB), &pPDBName);
    {
        FILE* fp = NULL;

        // Note that if you don't specify -Fd, a pdb name will be automatically generated. Use this file name to save the pdb so that PIX can find it quickly.
        _wfopen_s(&fp, pPDBName->GetStringPointer(), L"wb");
        fwrite(pPDB->GetBufferPointer(), pPDB->GetBufferSize(), 1, fp);
        fclose(fp);
    }

    //
    // Print hash.
    //
    CComPtr<IDxcBlob> pHash = nullptr;
    pResults->GetOutput(DXC_OUT_SHADER_HASH, IID_PPV_ARGS(&pHash), nullptr);
    if (pHash != nullptr)
    {
        wprintf(L"Hash: ");
        DxcShaderHash* pHashBuf = (DxcShaderHash*)pHash->GetBufferPointer();
        for (int i = 0; i < _countof(pHashBuf->HashDigest); i++)
            wprintf(L"%x", pHashBuf->HashDigest[i]);
        wprintf(L"\n");
    }


    //
    // Get separate reflection.
    //
    CComPtr<IDxcBlob> pReflectionData;
    pResults->GetOutput(DXC_OUT_REFLECTION, IID_PPV_ARGS(&pReflectionData), nullptr);
    if (pReflectionData != nullptr)
    {
        // Optionally, save reflection blob for later here.

        // Create reflection interface.
        DxcBuffer ReflectionData;
        ReflectionData.Encoding = DXC_CP_ACP;
        ReflectionData.Ptr = pReflectionData->GetBufferPointer();
        ReflectionData.Size = pReflectionData->GetBufferSize();

        CComPtr< ID3D12ShaderReflection > pReflection;
        pUtils->CreateReflection(&ReflectionData, IID_PPV_ARGS(&pReflection));

        // Use reflection interface here.
        
    }

    return 0;
}

使用自訂配置器

DxcCreateInstance2 是 dxcompiler 的進入點，可讓呼叫端提供 IMalloc 實作，用於所有涉及呼叫該物件的記憶體作業。若要提供有效的 IMalloc 實作，使用者必須實作能正確檢查支援之介面的 QueryInterface 方法，否則編譯器可能會當機。以下是範例程式碼供參考。

HRESULT STDMETHODCALLTYPE MyAllocator::QueryInterface(REFIID iid, void** ppvObject) override
{
    if (ppvObject == nullptr)
    {
        return E_POINTER;
    }
    *ppvObject = nullptr;

    if (IsEqualIID(iid, IID_IMalloc) || IsEqualIID(iid, IID_IUnknown)) {
        *ppvObject = reinterpret_cast<void*>(this);
        AddRef();
        return S_OK;
    }

    return E_NOINTERFACE;
}

XBOX DLL 介面延伸

使用 dxcompiler 介面預先編譯著色器之後，即可在 XBOX 上查詢特定的著色器統計資料。以下是範例程式碼 (為了簡潔起見已省略錯誤檢查)。

void PrintXboxShaderStats(IDxcBlob* pProgram)
{
    // load shader into Xbox container
    CComPtr<IDxcXboxContainer> pContainer;
    DxcCreateInstance(CLSID_DxcXboxContainer, __uuidof(IDxcXboxContainer), (void **)&pContainer);
    pContainer->Load(pProgram);

    // get hardware stage count
    UINT32 Count = 0;
    pContainer->GetNumShaders(&Count);

    for (UINT32 i = 0; i < Count; i++)
    {
        // get hardware shader stage interface
        CComPtr<IDxcXboxHwShader> hwShader;
        pContainer->GetShader(i, __uuidof(IDxcXboxHwShader), (void **)&hwShader);

        // get hardware stage name
        CComPtr<IDxcBlobUtf8> pStageName;
        hwShader->GetStageName(&pStageName);
        const char* szStageName = pStageName->GetStringPointer();

        // get hardware stage stats
        CComPtr<IDxcBlob> pStats;
        hwShader->GetShaderStats(DxcXboxShaderStatsClass::V1, 0, &pStats);
        DxcXboxShaderStaticsV1 stats;
        memcpy(&stats, pStats->GetBufferPointer(), sizeof(stats));

        // print stats
        printf("State Name: %s\n", szStageName);
        printf("NumVGPRs: %u\n", (UINT)stats.NumVGPR);
        printf("NumSGPRs: %u\n", (UINT)stats.NumSGPR);
        printf("WaveSize: %u\n", (UINT)stats.WaveSize);
        printf("Occupancy: %u\n", (UINT)stats.Occupancy);
        printf("ThreadGroupWaveCount: %u\n", (UINT)stats.ThreadGroupWaveCount);
        printf("LDSSizeInBytes: %u\n", (UINT)stats.LDSSizeInBytes);
        printf("PerLaneScratchSizeInBytes %u\n", (UINT)stats.PerLaneScratchSizeInBytes);
    }
}

另請參閱

著色器編譯器

​編譯器二進位檔

​DXC 命令列介面

​著色器雜湊

​反映

​PDBs

​精簡 .pdb

​關於編譯器版本的注意事項。

​新的 pdb 介面。

​光線追蹤的 .pdb (預覽)

​DXCompiler DLL 介面

​跨平台編譯

​使用編譯器介面

​使用自訂配置器

​XBOX DLL 介面延伸

​另請參閱

編譯器二進位檔

DXC 命令列介面

著色器雜湊

反映

PDBs

精簡 .pdb

關於編譯器版本的注意事項。

新的 pdb 介面。

光線追蹤的 .pdb (預覽)

DXCompiler DLL 介面

跨平台編譯

使用編譯器介面

使用自訂配置器

XBOX DLL 介面延伸

另請參閱