> ## 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.

# CreateCommandList

> CreateCommandList (XBOX 上的 Direct3D 12) — 建立命令清單。XBOX Direct3D 12 圖形參考。

建立命令清單。

## 語法

```cpp theme={null}
HRESULT CreateCommandList(
    UINT nodeMask,
    D3D12_COMMAND_LIST_TYPE type,
    ID3D12CommandAllocator  pCommandAllocator,
    ID3D12PipelineState  pInitialState,
    const IID & riid,
    void  ppCommandList
)
```

### 參數

*nodeMask \[in]*\
類型：UINT

若為單一 GPU 作業，請將此值設為零。如果有多個 GPU 節點，請設定一個位元來識別要為其建立命令清單的節點 (裝置的實體介面卡)。遮罩中的每個位元對應至單一節點。只能設定一個位元。另請參閱[多介面卡系統](https://learn.microsoft.com/en-us/windows/win32/direct3d12/multi-engine)。

*type \[in]*\
類型：D3D12\_COMMAND\_LIST\_TYPE

指定要建立的命令清單類型。

*pCommandAllocator \[in]*\
類型：ID3D12CommandAllocator \*

指向命令配置器物件的指標，裝置會從該物件建立命令清單。

*pInitialState \[in, optional]*\
類型：ID3D12PipelineState \*

指向管線狀態物件的選擇性指標，該物件包含命令清單的初始管線狀態。如果為 `nullptr`，執行階段會設定虛擬的初始管線狀態，讓驅動程式不必處理未定義的狀態。這麼做的額外負荷很低，特別是對命令清單而言，記錄命令清單的整體成本很可能遠超過單一初始狀態設定的成本。因此，如果設定初始管線狀態參數不方便，不設定它的成本很小。

另一方面，對於套件組合，嘗試設定初始狀態參數可能比較合理 (因為套件組合整體上可能較小，而且可以經常重複使用)。

*riid \[in]*\
類型：const IID &

要在 *ppCommandList* 中傳回之命令清單介面的全域唯一識別碼 (**GUID**) 參考。

*ppCommandList \[out]*\
類型：void \*\*

指向記憶體區塊的指標，該區塊會接收指向命令清單之 [ID3D12CommandList](/zh-TW/reference/graphics/d3d12/interfaces/id3d12commandlist/id3d12commandlist_public) 或 [ID3D12GraphicsCommandList](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12GraphicsCommandList/id3d12graphicscommandlist_xs) 介面的指標。

### 傳回值

類型：HRESULT

如果函式成功，會傳回 **S\_OK**。否則會傳回 [**HRESULT**](https://learn.microsoft.com/en-us/windows/desktop/com/structure-of-com-error-codes) [錯誤碼](https://learn.microsoft.com/en-us/windows/win32/com/com-error-codes-10)。

| 傳回值 | 描述 |
| - | - |
| E\_OUTOFMEMORY | 記憶體不足，無法建立命令清單。 |

如需其他可能的傳回值，請參閱 [Direct3D 12 傳回碼](https://learn.microsoft.com/en-us/windows/win32/direct3d12/d3d12-graphics-reference-returnvalues)。

## 備註

裝置會從命令配置器建立命令清單。

## 範例

[D3D12Bundles](https://learn.microsoft.com/en-us/windows/win32/direct3d12/working-samples) 範例使用 **ID3D12Device::CreateCommandList** 的方式如下。

建立管線物件。

```cpp theme={null}
ComPtr<ID3D12CommandAllocator> m_commandAllocator;
ComPtr<ID3D12GraphicsCommandList> m_commandList;
```

建立命令配置器。

```cpp theme={null}
ThrowIfFailed(m_device->CreateCommandAllocator(D3D12_COMMAND_LIST_TYPE_DIRECT, IID_PPV_ARGS(&m_commandAllocator)));
```

建立直接命令清單。

```cpp theme={null}
ThrowIfFailed(m_device->CreateCommandList(0, D3D12_COMMAND_LIST_TYPE_DIRECT, m_commandAllocator.Get(), nullptr, IID_PPV_ARGS(&m_commandList)));
```

請參閱 [D3D12 參考中的範例程式碼](https://learn.microsoft.com/en-us/windows/win32/direct3d12/notes-on-example-code)。

## 需求

**標頭：** d3d12\_xs.h 或 d3d12\_x.h\
**程式庫：** d3d12\_xs.lib 或 d3d12\_x.lib\
**支援的平台**：XBOX Series 主機與 XBOX One 系列

## 另請參閱

[ID3D12Device](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/id3d12device)

[ID3D12GraphicsCommandList::Reset](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_reset_public)


## Related topics

- [CreateCommandList1 (XBOX Series 主機)](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createcommandlist1_public.md)
- [CreateCommandAllocator](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createcommandallocator_public.md)
- [CreatePlacedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createplacedresource_public.md)
- [D3D12_CPU_DESCRIPTOR_HANDLE](/zh-TW/reference/graphics/d3d12/structs/d3d12_cpu_descriptor_handle_public.md)
- [CreateCommandQueue](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createcommandqueue_public.md)