ID3D12Device1::CreatePipelineLibrary-Methode (d3d12.h)

Artikel
07/16/2024

Erstellt eine zwischengespeicherte Pipelinebibliothek. Für Pipelinestatusobjekte (Pipeline State Objects, PSOs), die voraussichtlich Daten gemeinsam freigeben, bedeutet die Gruppierung in einer Bibliothek, bevor sie serialisiert werden, dass aufgrund von Metadaten weniger Aufwand entsteht, sowie die Möglichkeit, redundante oder duplizierte Daten, die auf den Datenträger geschrieben werden, zu vermeiden.

Sie können ID3D12PipelineLibrary Unterstützung mit ID3D12Device::CheckFeatureSupportmit D3D12_FEATURE_SHADER_CACHE und D3D12_FEATURE_DATA_SHADER_CACHEabfragen. Wenn das Flags-Element Mitglied von D3D12_FEATURE_DATA_SHADER_CACHE das Flag D3D12_SHADER_CACHE_SUPPORT_LIBRARYenthält, wird die ID3D12PipelineLibrary Schnittstelle unterstützt. Wenn dies nicht der Fall ist, wird DXGI_ERROR_NOT_SUPPORTED immer zurückgegeben, wenn diese Funktion aufgerufen wird.

Syntax

HRESULT CreatePipelineLibrary(
  const void *pLibraryBlob,
  SIZE_T     BlobLength,
  REFIID     riid,
  void       **ppPipelineLibrary
);

Parameter

pLibraryBlob

Typ: [in] const void*

Wenn der Eingabebibliotheks-BLOB leer ist, ist der anfängliche Inhalt der Bibliothek leer. Wenn der Eingabebibliotheks-BLOB nicht leer ist, wird es auf Integrität überprüft, analysiert und der Zeiger gespeichert. Der als Eingabe für diese Methode bereitgestellte Zeiger muss für die Lebensdauer des zurückgegebenen Objekts gültig bleiben. Aus Effizienzgründen werden die Daten nicht kopiert.

BlobLength

Typ: SIZE_T

Gibt die Länge pLibraryBlob- in Byte an.

riid

Typ: REFIID-

Gibt eine eindeutige REFIID für das ID3D12PipelineLibrary -Objekt an. Legen Sie in der Regel diesen und den folgenden Parameter mit dem Makro IID_PPV_ARGS(&Library)fest, wobei Library der Name des Objekts ist.

ppPipelineLibrary

Typ: [out] void**

Gibt einen Zeiger auf die erstellte Bibliothek zurück.

Rückgabewert

Typ: HRESULT-

Wenn die Funktion erfolgreich ist, wird S_OKzurückgegeben. Andernfalls wird ein HRESULT-Fehlercodezurückgegeben, einschließlich E_INVALIDARG, wenn das Blob beschädigt oder nicht erkannt wurde, D3D12_ERROR_DRIVER_VERSION_MISMATCH, wenn die bereitgestellten Daten von einem alten Treiber oder einer alten Laufzeit stammen, und D3D12_ERROR_ADAPTER_NOT_FOUND, wenn die Daten von einer anderen Hardware stammen.

Wenn Sie nullptr für pPipelineLibrary übergeben, führt die Laufzeit weiterhin die Überprüfung des Blobs durch, vermeiden Sie jedoch das Erstellen der tatsächlichen Bibliothek und gibt S_FALSE zurück, wenn die Bibliothek erstellt worden wäre.

Außerdem erfordert das Feature einen aktualisierten Treiber, und der Versuch, es auf alten Treibern zu verwenden, gibt DXGI_ERROR_UNSUPPORTED zurück.

Bemerkungen

Eine Pipelinebibliothek ermöglicht die folgenden Vorgänge.

Hinzufügen von Pipelinestatusobjekten (PSOs) zu einem vorhandenen Bibliotheksobjekt (siehe StorePipeline-).
Serialisieren einer PSO-Bibliothek in einen zusammenhängenden Speicherblock für Datenträgerspeicher (siehe Serialisieren).
De-Serialisieren einer PSO-Bibliothek vom beständigen Speicher (dies wird von CreatePipelineLibrarybehandelt).
Abrufen einzelner PSOs aus der Bibliothek (siehe LoadComputePipeline- und LoadGraphicsPipeline-).

Im Lebenszyklus einer Pipelinebibliothek gibt es keine Duplizierung zwischen PSOs mit identischen Unterkomponenten.

Eine empfohlene Lösung für die Verwaltung der Lebensdauer des bereitgestellten Zeigers, während nur die zurückgegebene Schnittstelle gezählt werden muss, besteht darin, ID3D12Object::SetPrivateDataInterfacezu nutzen und ein Objekt zu verwenden, das IUnknownimplementiert und den Speicher freigibt, wenn die Referenzanzahl 0 erreicht.

Threadsicherheit

Die Pipelinebibliothek ist threadsicher zu verwenden und wird bei Bedarf intern synchronisiert, mit einer Ausnahme: Mehrere Threads, die dasselbe PSO laden (über LoadComputePipeline, LoadGraphicsPipelineoder LoadPipeline) sollten sich synchronisieren, da dieser Akt den Zustand dieser Pipeline innerhalb der Bibliothek auf nicht threadsichere Weise ändern kann.

Beispiele

Siehe das Direct3D 12-Pipelinestatus-Cachebeispiel.

Anforderungen

Anforderung	Wert
Zielplattform-	Fenster
Header-	d3d12.h
Library	D3d12.lib
DLL-	D3d12.dll

Freigeben über