Metodo ID3D12Device1::CreatePipelineLibrary (d3d12.h)

Articolo
07/16/2024

Crea una libreria di pipeline memorizzata nella cache. Per gli oggetti di stato della pipeline (PSO) che devono condividere i dati insieme, raggrupparli in una libreria prima di serializzarli significa che è presente un sovraccarico inferiore a causa dei metadati, nonché l'opportunità di evitare la scrittura di dati ridondanti o duplicati su disco.

È possibile eseguire una query per supporto ID3D12PipelineLibrary con ID3D12Device::CheckFeatureSupport, con D3D12_FEATURE_SHADER_CACHE e D3D12_FEATURE_DATA_SHADER_CACHE. Se il membro Flags di D3D12_FEATURE_DATA_SHADER_CACHE contiene il flag D3D12_SHADER_CACHE_SUPPORT_LIBRARY, è supportata l'interfaccia ID3D12PipelineLibrary . In caso contrario, DXGI_ERROR_NOT_SUPPORTED verrà sempre restituito quando viene chiamata questa funzione.

Sintassi

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

Parametri

pLibraryBlob

Tipo: [in] const void*

Se il BLOB della libreria di input è vuoto, il contenuto iniziale della libreria è vuoto. Se il BLOB della libreria di input non è vuoto, viene convalidato per l'integrità, l'analisi e il puntatore viene archiviato. Il puntatore fornito come input per questo metodo deve rimanere valido per la durata dell'oggetto restituito. Per motivi di efficienza, i dati non sono copiati.

BlobLength

Tipo: SIZE_T

Specifica la lunghezza di pLibraryBlob in byte.

riid

Tipo: REFIID

Specifica un REFIID univoco per l'oggetto ID3D12PipelineLibrary. In genere impostare questo parametro e il parametro seguente con la macro IID_PPV_ARGS(&Library), dove Library è il nome dell'oggetto.

ppPipelineLibrary

Tipo: [out] void**

Restituisce un puntatore alla libreria creata.

Valore restituito

Tipo: HRESULT

Se la funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un HRESULTcodice di errore, incluso E_INVALIDARG se il BLOB è danneggiato o non riconosciuto, D3D12_ERROR_DRIVER_VERSION_MISMATCH se i dati forniti provengono da un driver o un runtime precedente e D3D12_ERROR_ADAPTER_NOT_FOUND se i dati provengono da hardware diverso.

Se si passa nullptr per pPipelineLibrary, il runtime esegue comunque la convalida del BLOB, ma evita di creare la libreria effettiva e restituisce S_FALSE se fosse stata creata la libreria.

Inoltre, la funzionalità richiede un driver aggiornato e il tentativo di usarlo sui driver precedenti restituirà DXGI_ERROR_UNSUPPORTED.

Osservazioni

Una libreria di pipeline abilita le operazioni seguenti.

Aggiunta di oggetti dello stato della pipeline (PSO) a un oggetto libreria esistente (vedere StorePipeline).
Serializzazione di una libreria PSO in un blocco contiguo di memoria per l'archiviazione su disco (vedere Serialize).
Deserializzazione di una libreria PSO dall'archiviazione permanente (gestita da CreatePipelineLibrary).
Recupero di singoli oggetti PSO dalla libreria (vedere LoadComputePipeline e LoadGraphicsPipeline).

A nessun punto del ciclo di vita di una libreria di pipeline è presente la duplicazione tra gli oggetti PSO con componenti secondari identici.

Una soluzione consigliata per la gestione della durata del puntatore fornito, mentre è sufficiente fare riferimento all'interfaccia restituita consiste nel sfruttare ID3D12Object::SetPrivateDataInterfacee usare un oggetto che implementa IUnknowne libera la memoria quando il conteggio dei riferimenti raggiunge 0.

Thread Safety

La libreria della pipeline è thread-safe da usare e verrà sincronizzata internamente in base alle esigenze, con un'eccezione: più thread che caricano lo stesso PSO (tramite LoadComputePipeline, LoadGraphicsPipelineo LoadPipeline) devono sincronizzarsi, in quanto questo atto può modificare lo stato della pipeline all'interno della libreria in modo non thread-safe.

Esempi

Vedere l'esempio della cache di stato della pipeline Direct3D 12.

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Finestre
intestazione	d3d12.h
libreria	D3d12.lib
dll	D3d12.dll

Condividi tramite