ID3D12Device::CreateCommandList method

Creates a command list.

Syntax

HRESULT CreateCommandList(
  UINT                    nodeMask,
  D3D12_COMMAND_LIST_TYPE type,
  ID3D12CommandAllocator  *pCommandAllocator,
  ID3D12PipelineState     *pInitialState,
  REFIID                  riid,
  void                    **ppCommandList
);

Parameters

nodeMask

Type: UINT

For single GPU operation, set this to zero. If there are multiple GPU nodes, set a bit to identify the node (the device's physical adapter) for which to create the command list. Each bit in the mask corresponds to a single node. Only 1 bit must be set. Refer to Multi-Adapter.

type

Type: D3D12_COMMAND_LIST_TYPE

A D3D12_COMMAND_LIST_TYPE-typed value that specifies the type of command list to create.

pCommandAllocator

Type: ID3D12CommandAllocator*

A pointer to the ID3D12CommandAllocator object that the device creates command lists from.

pInitialState

Type: ID3D12PipelineState*

A pointer to the ID3D12PipelineState object that contains the initial pipeline state for the command list. This is optional and can be NULL. If NULL, the runtime sets a dummy initial pipeline state so that drivers don't have to deal with undefined state. The overhead for this is low, particularly for a command list, for which the overall cost of recording the command list likely dwarfs the cost of one initial state setting. So there is little cost in not setting the initial pipeline state parameter if it isn't convenient.

For bundles on the other hand, it might make more sense to try to set the initial state parameter since bundles are likely smaller overall and can be reused frequently.

riid

Type: REFIID

The globally unique identifier (GUID) for the command list interface. The REFIID, or GUID, of the interface to the command list can be obtained by using the __uuidof() macro. For example, __uuidof(ID3D12CommandList) will get the GUID of the interface to a command list.

ppCommandList

Type: void**

A pointer to a memory block that receives a pointer to the ID3D12CommandListor ID3D12GraphicsCommandListinterface for the command list.

Return Value

Type: HRESULT

This method returns E_OUTOFMEMORY if there is insufficient memory to create the command list. See Direct3D 12 Return Codes for other possible return values.

Remarks

The device creates command lists from the command allocator.

Examples

The D3D12Bundles sample uses ID3D12Device::CreateCommandList as follows.

Create the pipeline objects.

ComPtr<ID3D12CommandAllocator> m_commandAllocator;
ComPtr<ID3D12GraphicsCommandList> m_commandList;

Create a command allocator.

ThrowIfFailed(m_device->CreateCommandAllocator(D3D12_COMMAND_LIST_TYPE_DIRECT, IID_PPV_ARGS(&m_commandAllocator)));

Creating the direct command list.

ThrowIfFailed(m_device->CreateCommandList(0, D3D12_COMMAND_LIST_TYPE_DIRECT, m_commandAllocator.Get(), nullptr, IID_PPV_ARGS(&m_commandList)));

Refer to the Example Code in the D3D12 Reference.

Requirements

   
Target Platform Windows
Header d3d12.h
Library D3D12.lib
DLL D3D12.dll

See Also

ID3D12Device

ID3D12GraphicsCommandList::Reset