D3DCompile2 函式 (d3dcompiler.h)

發行項
03/05/2024

將 Microsoft 高階著色器語言 (HLSL) 程式代碼編譯為指定目標的位元組程序代碼。

語法

HRESULT D3DCompile2(
  [in]            LPCVOID                pSrcData,
  [in]            SIZE_T                 SrcDataSize,
  [in, optional]  LPCSTR                 pSourceName,
  [in, optional]  const D3D_SHADER_MACRO *pDefines,
  [in, optional]  ID3DInclude            *pInclude,
  [in]            LPCSTR                 pEntrypoint,
  [in]            LPCSTR                 pTarget,
  [in]            UINT                   Flags1,
  [in]            UINT                   Flags2,
  [in]            UINT                   SecondaryDataFlags,
  [in, optional]  LPCVOID                pSecondaryData,
  [in]            SIZE_T                 SecondaryDataSize,
  [out]           ID3DBlob               **ppCode,
  [out, optional] ID3DBlob               **ppErrorMsgs
);

參數

[in] pSrcData

類型： LPCVOID

ASCII HLSL 程式代碼 () 之未編譯著色器數據的指標。

[in] SrcDataSize

類型： SIZE_T

pSrcData 指向之內存區塊的大小，以位元組為單位。

[in, optional] pSourceName

類型： LPCSTR

常數 Null 終止字串的選擇性指標，其中包含用來識別錯誤訊息中使用的源數據名稱。如果未使用，請將設定為 NULL。

[in, optional] pDefines

類型： const D3D_SHADER_MACRO*

定義著色器宏之 D3D_SHADER_MACRO 結構的選擇性陣列。每個宏定義都包含名稱和以 Null 結尾的定義。如果未使用，請將設定為 NULL。陣列中的最後一個結構做為終止符，而且必須將所有成員設定為 NULL。

[in, optional] pInclude

類型： ID3DInclude*

ID3DInclude 介面的指標，編譯程式用來處理包含檔案。如果您將此參數設定為 NULL ，且著色器包含 #include，就會發生編譯錯誤。您可以傳遞 D3D_COMPILE_STANDARD_FILE_INCLUDE 宏，這是預設 include 處理程式的指標。此預設包含處理程式包含相對於目前目錄的檔案，以及相對於初始原始程式檔目錄的檔案。當您使用 D3D_COMPILE_STANDARD_FILE_INCLUDE 時，必須在 pSourceName 參數中指定來源檔名;編譯程式會從 pSourceName 衍生初始相對目錄。

#define D3D_COMPILE_STANDARD_FILE_INCLUDE ((ID3DInclude*)(UINT_PTR)1)

[in] pEntrypoint

類型： LPCSTR

常數 Null 終止字串的指標，其中包含著色器執行開始之著色器進入點函式的名稱。當您編譯效果時， D3DCompile2 會忽略 pEntrypoint;我們建議您將 pEntrypoint 設定為 NULL ，因為如果呼叫的函式不會使用它，最好是將指標參數設定為 NULL 。

[in] pTarget

類型： LPCSTR

常數 Null 終止字串的指標，指定要編譯的著色器目標或著色器功能集。著色器目標可以是著色器模型 (例如著色器模型 2、著色器模型 3、著色器模型 4 或著色器模型 5) 。例如，目標也可以是效果類型 (，例如fx_4_1) 。如需各種配置檔支援的目標相關信息，請參閱指定編譯程序目標。

[in] Flags1

類型： UINT

著色器 D3D 編譯常數的組合，使用位 OR 運算結合。產生的值會指定編譯程式如何編譯 HLSL 程式代碼。

[in] Flags2

類型： UINT

效果 D3D 編譯效果常數的組合，使用位 OR 運算結合。產生的值會指定編譯程式如何編譯效果。當您編譯著色器而非效果檔案時， D3DCompile2 會忽略 Flags2;我們建議您將 Flags2 設定為零，因為如果呼叫的函式不會使用它，則良好的程式設計做法是將非pointer 參數設定為零。

[in] SecondaryDataFlags

類型： UINT

使用位 OR 運算結合的下列旗標組合。產生的值會指定編譯程式如何編譯 HLSL 程式代碼。

旗標	描述
D3DCOMPILE_SECDATA_MERGE_UAV_SLOTS (0x01)	在 pSecondaryData 參數指向的次要數據中，合並未排序的存取檢視 (UAV) 位置。
D3DCOMPILE_SECDATA_PRESERVE_TEMPLATE_SLOTS (0x02)	保留 pSecondaryData 參數指向之次要數據中的範本位置。
D3DCOMPILE_SECDATA_REQUIRE_TEMPLATE_MATCH (0x04)	要求 pSecondaryData 參數在編譯 HLSL 程式代碼時，次要數據中的範本必須相符。

如果 pSecondaryData 為 NULL，請將設定為零。

[in, optional] pSecondaryData

類型： LPCVOID

次要數據的指標。如果您未傳遞次要數據，請將設定為 NULL。使用此次要數據來對齊兩個著色器中的 UAV 位置。假設著色器 A 具有 UAV，且它們系結至某些位置。若要編譯著色器 B，讓具有相同名稱的UAV 對應至與 A 中相同的位置，請將 A 的位元組程式代碼傳遞至 D3DCompile2 做為次要數據。

[in] SecondaryDataSize

類型： SIZE_T

pSecondaryData 所指向記憶體區塊的大小，以位元組為單位。如果 pSecondaryData 為 NULL，請將設定為零。

[out] ppCode

類型： ID3DBlob**

可接收 ID3DBlob 介面指標的變數指標，可用來存取編譯的程序代碼。

[out, optional] ppErrorMsgs

類型： ID3DBlob**

可接收 ID3DBlob 介面指標的變數指標，您可以用來存取編譯程式錯誤訊息，如果沒有錯誤，則為 NULL 。

傳回值

類型： HRESULT

傳回其中一個 Direct3D 11 傳回碼。

備註

D3DCompile2 與 D3DCompile 之間的差異在於 D3DCompile2 會採用一些選擇性參數 (SecondaryDataFlags、pSecondaryData 和 SecondaryDataSize) ，可用來控制位元組程式代碼產生方式的某些層面。如需詳細資訊，請參閱這些參數的描述。否則，在 D3DCompile2 與 D3DCompile2 之間產生的位元組程式代碼效率沒有差異。

編譯UWP的著色器

若要編譯脫機著色器，建議的方法是使用 Effect-compiler 工具。如果您無法事先編譯所有著色器，請考慮編譯成本較高的著色器，以及您的啟動和大部分效能敏感性路徑所需的著色器，並在運行時間編譯其餘部分。您可以使用類似下列的程式，在UWP應用程式中編譯載入或產生的著色器，而不會封鎖您的使用者介面線程。

使用 Visual Studio 2015+ 開發 UWP 應用程式，新增專案 “shader.hlsl”。
- 在 Visual Studio 的 [ 方案資料夾 ] 檢視中，選取 著色器.hlsl 專案，以滑鼠右鍵按兩下 [屬性]。
- 請確定專案 [內容 ] 設定為 [是]。
- 請確定 [項目類型 ] 設定為 [文字]。
- 將按鈕新增至 XAML，在此範例中將它命名為適當 (“TheButton”，) ，然後新增 Click 處理程式。

現在，將這些包含新增至您的.cpp檔案：

#include <ppltasks.h>
#include <d3dcompiler.h>
#include <Robuffer.h>

使用下列程式代碼來呼叫 D3DCompile2。請注意，此處沒有錯誤檢查或處理，而且此程式代碼也示範您可以在背景中執行 I/O 和編譯，讓您的 UI 更具回應性。

void App1::DirectXPage::TheButton_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
  std::shared_ptr<Microsoft::WRL::ComPtr<ID3DBlob>> blobRef = std::make_shared<Microsoft::WRL::ComPtr<ID3DBlob>>();

  // Load a file and compile it.
  auto fileOp = Windows::ApplicationModel::Package::Current->InstalledLocation->GetFileAsync(L"shader.hlsl");
  create_task(fileOp).then([this](Windows::Storage::StorageFile^ file) -> IAsyncOperation<Windows::Storage::Streams::IBuffer^>^
  {
    // Do file I/O in background thread (use_arbitrary).
    return Windows::Storage::FileIO::ReadBufferAsync(file);
  }, task_continuation_context::use_arbitrary())
    .then([this, blobRef](Windows::Storage::Streams::IBuffer^ buffer)
  {
    // Do compilation in background thread (use_arbitrary).

    // Cast to Object^, then to its underlying IInspectable interface.
    Microsoft::WRL::ComPtr<IInspectable> insp(reinterpret_cast<IInspectable*>(buffer));

    // Query the IBufferByteAccess interface.
    Microsoft::WRL::ComPtr<Windows::Storage::Streams::IBufferByteAccess> bufferByteAccess;
    insp.As(&bufferByteAccess);

    // Retrieve the buffer data.
    byte *pBytes = nullptr;
    bufferByteAccess->Buffer(&pBytes);

    Microsoft::WRL::ComPtr<ID3DBlob> blob;
    Microsoft::WRL::ComPtr<ID3DBlob> errMsgs;
    D3DCompile2(pBytes, buffer->Length, "shader.hlsl", nullptr, nullptr, "main", "ps_5_0", 0, 0, 0, nullptr, 0, blob.GetAddressOf(), errMsgs.GetAddressOf());
    *blobRef = blob;
  }, task_continuation_context::use_arbitrary())
    .then([this, blobRef]()
  {
    // Update UI / use shader on foreground thread.
    wchar_t message[40];
    swprintf_s(message, L"blob is %u bytes long", (unsigned)(*blobRef)->GetBufferSize());
    this->TheButton->Content = ref new Platform::String(message);
  }, task_continuation_context::use_current());
}

規格需求

需求	值
目標平台	Windows
標頭	d3dcompiler.h
程式庫	D3DCompiler.lib
Dll	D3DCompiler_47.dll

共用方式為

D3DCompile2 函式 (d3dcompiler.h)

語法

參數

傳回值

備註

編譯UWP的著色器

規格需求

請參閱

意見反應

其他資源