> ## 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](/reference/graphics/d3d12/interfaces/id3d12commandlist/id3d12commandlist_public) 或 [ID3D12GraphicsCommandList](/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](/reference/graphics/d3d12_x/interfaces/id3d12device/id3d12device)

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


## Related topics

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