Metodo ID3D12Device1::CreatePipelineLibrary (d3d12.h)

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

Vedere anche

• ID3D12Device1
• esempio di cache dello stato della pipeline Direct3D 12