> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CreatePipelineLibrary

> 创建缓存的管线库。

创建缓存的管线库。对于预期共同共享数据的管线状态对象 (PSO)，在序列化前将它们分组到一个库中意味着元数据带来的开销更小，同时也有机会避免向磁盘写入冗余或重复的数据。

您可以通过 [**ID3D12Device::CheckFeatureSupport**](/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_checkfeaturesupport_public)，配合 [**D3D12\_FEATURE\_SHADER\_CACHE**](/reference/graphics/d3d12/enums/d3d12_feature_public) 和 [**D3D12\_FEATURE\_DATA\_SHADER\_CACHE**](/reference/graphics/d3d12/structs/d3d12_feature_data_shader_cache_public) 查询对 **ID3D12PipelineLibrary** 的支持情况。如果 [**D3D12\_FEATURE\_DATA\_SHADER\_CACHE**](/reference/graphics/d3d12/structs/d3d12_feature_data_shader_cache_public) 的 *Flags* 成员包含标志 [**D3D12\_SHADER\_CACHE\_SUPPORT\_LIBRARY**](/reference/graphics/d3d12/enums/d3d12_shader_cache_support_flags_public)，则支持 **ID3D12PipelineLibrary** 接口。否则，调用此函数时将始终返回 **DXGI\_ERROR\_NOT\_SUPPORTED**。

## 语法

```cpp theme={null}
HRESULT CreatePipelineLibrary(
    const void  pLibraryBlob,
    SIZE_T BlobLength,
    const IID & riid,
    void  ppPipelineLibrary
)
```

### 参数

*pLibraryBlob*<br />类型：const void \*

如果输入的库 blob 为空，则库的初始内容为空。如果输入的库 blob 不为空，则会验证其完整性、进行解析，并存储该指针。作为此方法输入的指针必须在返回对象的整个生命周期内保持有效。出于效率考虑，不会复制数据。

*BlobLength*<br />类型：SIZE\_T

指定 *pLibraryBlob* 的长度（以字节为单位）。

*riid*<br />类型：const IID &

为 [ID3D12PipelineLibrary](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/id3d12pipelinelibrary_public) 对象指定唯一的 REFIID。通常使用宏 `IID_PPV_ARGS(&Library)` 同时设置此参数和下一个参数，其中 **Library** 是对象的名称。

*ppPipelineLibrary*<br />类型：void \*\*

返回指向所创建库的指针。

### 返回值

类型：HRESULT

如果函数成功，则返回 **S\_OK**。否则，返回 [**HRESULT**](https://learn.microsoft.com/en-us/windows/win32/com/structure-of-com-error-codes) [错误代码](https://learn.microsoft.com/en-us/windows/win32/com/com-error-codes-10)，包括：如果 blob 已损坏或无法识别，则返回 **E\_INVALIDARG**；如果提供的数据来自旧驱动程序或运行时，则返回 **D3D12\_ERROR\_DRIVER\_VERSION\_MISMATCH**；如果数据来自不同的硬件，则返回 **D3D12\_ERROR\_ADAPTER\_NOT\_FOUND**。

如果为 *pPipelineLibrary* 传入 `nullptr`，则运行时仍会执行对 blob 的验证，但不会实际创建库；如果本可以创建库，则返回 S\_FALSE。

此外，该功能需要更新驱动程序，在旧驱动程序上尝试使用时将返回 DXGI\_ERROR\_UNSUPPORTED。

## 备注

管线库支持以下操作。

* 向现有库对象添加管线状态对象 (PSO)（请参阅 [StorePipeline](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_storepipeline_public)）。
* 将 PSO 库序列化为连续的内存块以进行磁盘存储（请参阅 [Serialize](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_serialize_public)）。
* 从持久性存储反序列化 PSO 库（这由 **CreatePipelineLibrary** 处理）。
* 从库中检索单个 PSO（请参阅 [LoadComputePipeline](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadcomputepipeline_public) 和 [LoadGraphicsPipeline](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadgraphicspipeline_public)）。

在管线库的整个生命周期中，任何时候都不存在具有相同子组件的 PSO 之间的重复。

对于在只需要对返回接口进行引用计数的情况下管理所提供指针生命周期的推荐做法是：利用 [ID3D12Object::SetPrivateDataInterface](/reference/graphics/d3d12/interfaces/id3d12object/methods/id3d12object_setprivatedatainterface_public)，并使用一个实现了 **IUnknown** 的对象，在引用计数达到 0 时释放内存。

### 线程安全

管线库的使用是线程安全的，会根据需要在内部进行同步，但有一个例外：多个线程加载同一 PSO（通过 [**LoadComputePipeline**](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadcomputepipeline_public)、[**LoadGraphicsPipeline**](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadgraphicspipeline_public) 或 [**LoadPipeline**](/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary1/methods/id3d12pipelinelibrary1_loadpipeline_public)）时应自行同步，因为该操作可能以非线程安全的方式修改该管线在库中的状态。

## 示例

请参阅 [Direct3D 12 管线状态缓存示例](https://github.com/microsoft/DirectX-Graphics-Samples/tree/master/Samples/Desktop/D3D12PipelineStateCache)。

## 要求

**头文件：** d3d12\_xs.h 或 d3d12\_x.h<br />**库：** d3d12\_xs.lib 或 d3d12\_x.lib<br />**支持的平台**：XBOX Series 主机和 XBOX One 系列

## 另请参阅

* [ID3D12Device1](/reference/graphics/d3d12/interfaces/id3d12device1/id3d12device1_public)
* [Direct3D 12 管线状态缓存示例](https://github.com/microsoft/DirectX-Graphics-Samples/tree/master/Samples/Desktop/D3D12PipelineStateCache)


## Related topics

- [ID3D12PipelineLibrary](/zh-CN/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/id3d12pipelinelibrary_public.md)
- [StorePipeline](/zh-CN/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_storepipeline_public.md)
- [LoadComputePipeline](/zh-CN/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadcomputepipeline_public.md)
- [LoadGraphicsPipeline](/zh-CN/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadgraphicspipeline_public.md)
- [Serialize](/zh-CN/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_serialize_public.md)