Freigeben über


D3DCompile2-Funktion (d3dcompiler.h)

Kompiliert Microsoft High Level Shader Language (HLSL)-Code in Bytecode für ein bestimmtes Ziel.

Syntax

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

Parameter

[in] pSrcData

Typ: LPCVOID

Ein Zeiger auf nicht kompilierte Shaderdaten (ASCII HLSL-Code).

[in] SrcDataSize

Typ: SIZE_T

Die Größe des Speicherblocks in Bytes, auf den pSrcData verweist.

[in, optional] pSourceName

Typ: LPCSTR

Ein optionaler Zeiger auf eine konstante NULL-Zeichenfolge, die den Namen enthält, der die Quelldaten identifiziert, die in Fehlermeldungen verwendet werden sollen. Wenn nicht verwendet, legen Sie auf NULL fest.

[in, optional] pDefines

Typ: const D3D_SHADER_MACRO*

Ein optionales Array von D3D_SHADER_MACRO Strukturen, die Shadermakros definieren. Jede Makrodefinition enthält einen Namen und eine NULL-beendete Definition. Wenn nicht verwendet, legen Sie auf NULL fest. Die letzte Struktur im Array dient als Abschlussator, und alle Member müssen auf NULL festgelegt sein.

[in, optional] pInclude

Typ: ID3DInclude*

Ein Zeiger auf eine ID3DInclude-Schnittstelle , die der Compiler zum Verarbeiten von Includedateien verwendet. Wenn Sie diesen Parameter auf NULL festlegen und der Shader eine #include enthält, tritt ein Kompilierungsfehler auf. Sie können das D3D_COMPILE_STANDARD_FILE_INCLUDE Makro übergeben, bei dem es sich um einen Zeiger auf einen standardmäßigen Includehandler handelt. Dieser Standardmäßige Include-Handler enthält Dateien, die relativ zum aktuellen Verzeichnis sind, und Dateien, die relativ zum Verzeichnis der ursprünglichen Quelldatei sind. Wenn Sie D3D_COMPILE_STANDARD_FILE_INCLUDE verwenden, müssen Sie den Namen der Quelldatei im pSourceName-Parameter angeben. der Compiler leitet das anfängliche relative Verzeichnis von pSourceName ab.

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

[in] pEntrypoint

Typ: LPCSTR

Ein Zeiger auf eine konstante NULL-Zeichenfolge, die den Namen der Shadereinstiegspunktfunktion enthält, in der die Shaderausführung beginnt. Wenn Sie einen Effekt kompilieren, ignoriert D3DCompile2pEntrypoint; Es wird empfohlen, pEntrypoint auf NULL festzulegen, da es eine gute Programmierpraxis ist, einen Zeigerparameter auf NULL festzulegen, wenn die aufgerufene Funktion ihn nicht verwendet.

[in] pTarget

Typ: LPCSTR

Ein Zeiger auf eine konstante NULL-Zeichenfolge, die das Shaderziel oder die Gruppe von Shaderfeatures angibt, für die kompiliert werden soll. Das Shaderziel kann ein Shadermodell sein (z. B. Shadermodell 2, Shadermodell 3, Shadermodell 4 oder Shadermodell 5). Das Ziel kann auch ein Effekttyp sein (z. B. fx_4_1). Informationen zu den Zielen, die von verschiedenen Profilen unterstützt werden, finden Sie unter Angeben von Compilerzielen.

[in] Flags1

Typ: UINT

Eine Kombination aus Shader-D3D-Kompilierkonstanten , die mithilfe eines bitweisen OR-Vorgangs kombiniert werden. Der resultierende Wert gibt an, wie der Compiler den HLSL-Code kompiliert.

[in] Flags2

Typ: UINT

Eine Kombination von Effekt-D3D-Kompilierungseffektkonstanten , die mithilfe eines bitweisen OR-Vorgangs kombiniert werden. Der resultierende Wert gibt an, wie der Compiler den Effekt kompiliert. Wenn Sie einen Shader und keine Effektdatei kompilieren, ignoriert D3DCompile2Flags2. Es wird empfohlen, Flags2 auf 0 festzulegen, da es eine gute Programmierpraxis ist, einen Nichtpointerparameter auf 0 festzulegen, wenn die aufgerufene Funktion ihn nicht verwendet.

[in] SecondaryDataFlags

Typ: UINT

Eine Kombination der folgenden Flags, die mithilfe eines bitweisen OR-Vorgangs kombiniert werden. Der resultierende Wert gibt an, wie der Compiler den HLSL-Code kompiliert.

Flag Beschreibung
D3DCOMPILE_SECDATA_MERGE_UAV_SLOTS (0x01) Führen Sie UAV-Slots (Unordered Access View) in den sekundären Daten zusammen, auf die der pSecondaryData-Parameter verweist.
D3DCOMPILE_SECDATA_PRESERVE_TEMPLATE_SLOTS (0x02) Behalten Sie Vorlagenslots in den sekundären Daten bei, auf die der pSecondaryData-Parameter verweist.
D3DCOMPILE_SECDATA_REQUIRE_TEMPLATE_MATCH (0x04) Erfordern Sie, dass Vorlagen in den sekundären Daten, auf die der pSecondaryData-Parameter verweist, beim Kompilieren des HLSL-Codes durch den Compiler festgelegt werden.

Wenn pSecondaryDataNULL ist, legen Sie auf Null fest.

[in, optional] pSecondaryData

Typ: LPCVOID

Ein Zeiger auf sekundäre Daten. Wenn Sie sekundäre Daten nicht übergeben, legen Sie auf NULL fest. Verwenden Sie diese sekundären Daten, um UAV-Slots in zwei Shadern auszurichten. Angenommen, Shader A verfügt über UAVs, die an einige Slots gebunden sind. Um Shader B so zu kompilieren, dass UAVs mit denselben Namen in B den gleichen Slots wie in A zugeordnet werden, übergeben Sie den Bytecode von A an D3DCompile2 als sekundäre Daten.

[in] SecondaryDataSize

Typ: SIZE_T

Die Größe des Speicherblocks in Bytes, auf den pSecondaryData verweist. Wenn pSecondaryDataNULL ist, legen Sie auf Null fest.

[out] ppCode

Typ: ID3DBlob**

Ein Zeiger auf eine Variable, die einen Zeiger auf die ID3DBlob-Schnittstelle empfängt, die Sie für den Zugriff auf den kompilierten Code verwenden können.

[out, optional] ppErrorMsgs

Typ: ID3DBlob**

Ein Zeiger auf eine Variable, die einen Zeiger auf die ID3DBlob-Schnittstelle empfängt, mit der Sie auf Compilerfehlermeldungen zugreifen können, oder NULL , wenn keine Fehler vorliegen.

Rückgabewert

Typ: HRESULT

Gibt einen der Direct3D 11-Rückgabecodes zurück.

Hinweise

Der Unterschied zwischen D3DCompile2 und D3DCompile besteht darin, dass D3DCompile2 einige optionale Parameter (SecondaryDataFlags, pSecondaryData und SecondaryDataSize) verwendet, mit denen einige Aspekte der Bytecodegenerierung gesteuert werden können. Weitere Informationen finden Sie in den Beschreibungen dieser Parameter. Andernfalls gibt es keinen Unterschied zur Effizienz des zwischen D3DCompile2 und D3DCompile generierten Bytecodes.

Kompilieren von Shadern für UWP

Zum Kompilieren von Offline-Shadern empfiehlt sich die Verwendung des Effect-Compiler-Tools. Wenn Sie nicht alle Ihre Shader im Voraus kompilieren können, sollten Sie die teureren und die, die Ihr Startpfad und die meisten leistungssensitiven Pfade erfordert, kompilieren und den Rest zur Laufzeit kompilieren. Sie können einen Prozess ähnlich dem folgenden verwenden, um einen geladenen oder generierten Shader in einer UWP-Anwendung zu kompilieren, ohne Ihren Benutzeroberflächesthread zu blockieren.

  • Fügen Sie mithilfe von Visual Studio 2015+ zum Entwickeln der UWP-App das neue Element "shader.hlsl" hinzu.

    • Wählen Sie in der Projektmappenordneransicht von Visual Studio das Element shaders.hlsl aus, und klicken Sie mit der rechten Maustaste auf Eigenschaften.
    • Stellen Sie sicher, dass das Element Inhalt auf Ja festgelegt ist.
    • Stellen Sie sicher, dass der Elementtyp auf Text festgelegt ist.
    • Fügen Sie XAML eine Schaltfläche hinzu, benennen Sie sie entsprechend ("TheButton" in diesem Beispiel), und fügen Sie einen Click-Handler hinzu.
  • Fügen Sie nun die folgenden Includes zu Ihrer .cpp-Datei hinzu:

    #include <ppltasks.h>
    #include <d3dcompiler.h>
    #include <Robuffer.h>
    
  • Verwenden Sie den folgenden Code, um D3DCompile2 aufzurufen. Beachten Sie, dass es hier keine Fehlerüberprüfung oder -behandlung gibt und dass dieser Code veranschaulicht, dass Sie sowohl E/A als auch Kompilierung im Hintergrund ausführen können, sodass Ihre Benutzeroberfläche reaktionsfähiger ist.

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

Anforderungen

Anforderung Wert
Zielplattform Windows
Kopfzeile d3dcompiler.h
Bibliothek D3DCompiler.lib
DLL D3DCompiler_47.dll

Siehe auch