> ## 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**](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_checkfeaturesupport_public) 搭配 [**D3D12\_FEATURE\_SHADER\_CACHE**](/zh-TW/reference/graphics/d3d12/enums/d3d12_feature_public) 和 [**D3D12\_FEATURE\_DATA\_SHADER\_CACHE**](/zh-TW/reference/graphics/d3d12/structs/d3d12_feature_data_shader_cache_public)，查詢是否支援 **ID3D12PipelineLibrary**。如果 [**D3D12\_FEATURE\_DATA\_SHADER\_CACHE**](/zh-TW/reference/graphics/d3d12/structs/d3d12_feature_data_shader_cache_public) 的 *Flags* 成員包含旗標 [**D3D12\_SHADER\_CACHE\_SUPPORT\_LIBRARY**](/zh-TW/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*\
類型：const void \*

如果輸入的程式庫 Blob 是空的，則程式庫的初始內容是空的。如果輸入的程式庫 Blob 不是空的，則會驗證其完整性、加以剖析，並儲存指標。作為此方法輸入所提供的指標，在傳回物件的存留期間內必須保持有效。基於效率考量，不會複製資料。

*BlobLength*\
類型：SIZE\_T

指定 *pLibraryBlob* 的長度 (以位元組為單位)。

*riid*\
類型：const IID &

指定 [ID3D12PipelineLibrary](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/id3d12pipelinelibrary_public) 物件的唯一 REFIID。通常會使用巨集 `IID_PPV_ARGS(&Library)` 設定此參數和下一個參數，其中 **Library** 是物件的名稱。

*ppPipelineLibrary*\
類型：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](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_storepipeline_public))。
* 將 PSO 程式庫序列化為連續的記憶體區塊以供磁碟儲存 (請參閱 [Serialize](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_serialize_public))。
* 從永續性儲存體還原序列化 PSO 程式庫 (由 **CreatePipelineLibrary** 處理)。
* 從程式庫擷取個別 PSO (請參閱 [LoadComputePipeline](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadcomputepipeline_public) 和 [LoadGraphicsPipeline](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadgraphicspipeline_public))。

在管線程式庫生命週期的任何時間點，具有相同子元件的 PSO 之間都不會發生重複。

若要管理所提供指標的存留期，同時只需對傳回的介面進行參考計數，建議的解決方案是利用 [ID3D12Object::SetPrivateDataInterface](/zh-TW/reference/graphics/d3d12/interfaces/id3d12object/methods/id3d12object_setprivatedatainterface_public)，並使用實作 **IUnknown** 的物件，在參考計數達到 0 時釋放記憶體。

### 執行緒安全性

管線程式庫可安全地在多執行緒中使用，並會視需要在內部進行同步處理，但有一個例外：多個執行緒載入相同的 PSO (透過 [**LoadComputePipeline**](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadcomputepipeline_public)、[**LoadGraphicsPipeline**](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadgraphicspipeline_public) 或 [**LoadPipeline**](/zh-TW/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\
**程式庫：** d3d12\_xs.lib 或 d3d12\_x.lib\
**支援的平台**：XBOX Series 主機與 XBOX One 系列

## 另請參閱

* [ID3D12Device1](/zh-TW/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-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/id3d12pipelinelibrary_public.md)
- [StorePipeline](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_storepipeline_public.md)
- [LoadComputePipeline](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadcomputepipeline_public.md)
- [LoadGraphicsPipeline](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_loadgraphicspipeline_public.md)
- [GetSerializedSize](/zh-TW/reference/graphics/d3d12/interfaces/id3d12pipelinelibrary/methods/id3d12pipelinelibrary_getserializedsize_public.md)