ID3D12Device1::CreatePipelineLibrary method (d3d12.h)

Article
08/03/2021

Creates a cached pipeline library. For pipeline state objects (PSOs) that are expected to share data together, grouping them into a library before serializing them means that there's less overhead due to metadata, as well as the opportunity to avoid redundant or duplicated data being written to disk.

You can query for ID3D12PipelineLibrary support with ID3D12Device::CheckFeatureSupport, with D3D12_FEATURE_SHADER_CACHE and D3D12_FEATURE_DATA_SHADER_CACHE. If the Flags member of D3D12_FEATURE_DATA_SHADER_CACHE contains the flag D3D12_SHADER_CACHE_SUPPORT_LIBRARY, the ID3D12PipelineLibrary interface is supported. If not, then DXGI_ERROR_NOT_SUPPORTED will always be returned when this function is called.

Syntax

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

Parameters

pLibraryBlob

Type: [in] const void*

If the input library blob is empty, then the initial content of the library is empty. If the input library blob is not empty, then it is validated for integrity, parsed, and the pointer is stored. The pointer provided as input to this method must remain valid for the lifetime of the object returned. For efficiency reasons, the data is not copied.

BlobLength

Type: SIZE_T

Specifies the length of pLibraryBlob in bytes.

riid

Type: REFIID

Specifies a unique REFIID for the ID3D12PipelineLibrary object. Typically set this and the following parameter with the macro IID_PPV_ARGS(&Library), where Library is the name of the object.

ppPipelineLibrary

Type: [out] void**

Returns a pointer to the created library.

Return value

Type: HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code, including E_INVALIDARG if the blob is corrupted or unrecognized, D3D12_ERROR_DRIVER_VERSION_MISMATCH if the provided data came from an old driver or runtime, and D3D12_ERROR_ADAPTER_NOT_FOUND if the data came from different hardware.

If you pass nullptr for pPipelineLibrary then the runtime still performs the validation of the blob but avoid creating the actual library and returns S_FALSE if the library would have been created.

Also, the feature requires an updated driver, and attempting to use it on old drivers will return DXGI_ERROR_UNSUPPORTED.

Remarks

A pipeline library enables the following operations.

Adding pipeline state objects (PSOs) to an existing library object (refer to StorePipeline).
Serializing a PSO library into a contiguous block of memory for disk storage (refer to Serialize).
De-serializing a PSO library from persistent storage (this is handled by CreatePipelineLibrary).
Retrieving individual PSOs from the library (refer to LoadComputePipeline and LoadGraphicsPipeline).

At no point in the lifecycle of a pipeline library is there duplication between PSOs with identical sub-components.

A recommended solution for managing the lifetime of the provided pointer while only having to ref-count the returned interface is to leverage ID3D12Object::SetPrivateDataInterface, and use an object which implements IUnknown, and frees the memory when the ref-count reaches 0.

Thread Safety

The pipeline library is thread-safe to use, and will internally synchronize as necessary, with one exception: multiple threads loading the same PSO (via LoadComputePipeline, LoadGraphicsPipeline, or LoadPipeline) should synchronize themselves, as this act may modify the state of that pipeline within the library in a non-thread-safe manner.

Examples

See the Direct3D 12 pipeline state cache sample.

Requirements

Requirement	Value
Target Platform	Windows
Header	d3d12.h
Library	D3d12.lib
DLL	D3d12.dll

Share via