ID3D12GraphicsCommandList interface

Encapsulates a list of graphics commands for rendering. Includes APIs for instrumenting the command list execution, and for setting and clearing the pipeline state.

Note  The latest version of this interface is ID3D12GraphicsCommandList1 introduced in the Windows 10 Creators Update. Applications targetting Windows 10 Creators Update should use the ID3D12GraphicsCommandList1 interface instead of ID3D12GraphicsCommandList.
 

Methods

The ID3D12GraphicsCommandList interface has these methods.

Method Description
ID3D12GraphicsCommandList::BeginEvent Not intended to be called directly.  Use the PIX event runtime to insert events into a command list.
ID3D12GraphicsCommandList::BeginQuery Starts a query running.
ID3D12GraphicsCommandList::ClearDepthStencilView Clears the depth-stencil resource.
ID3D12GraphicsCommandList::ClearRenderTargetView Sets all the elements in a render target to one value.
ID3D12GraphicsCommandList::ClearState Resets the state of a direct command list back to the state it was in when the command list was created.
ID3D12GraphicsCommandList::ClearUnorderedAccessViewFloat Sets all the elements in a unordered access view to the specified float values.
ID3D12GraphicsCommandList::ClearUnorderedAccessViewUint Sets all the elements in a unordered-access view to the specified integer values.
ID3D12GraphicsCommandList::Close Indicates that recording to the command list has finished.
ID3D12GraphicsCommandList::CopyBufferRegion Copies a region of a buffer from one resource to another.
ID3D12GraphicsCommandList::CopyResource Copies the entire contents of the source resource to the destination resource.
ID3D12GraphicsCommandList::CopyTextureRegion This method uses the GPU to copy texture data between two locations. Both the source and the destination may reference texture data located within either a buffer resource or a texture resource.
ID3D12GraphicsCommandList::CopyTiles Copies tiles from buffer to tiled resource or vice versa.
ID3D12GraphicsCommandList::DiscardResource Discards a resource.
ID3D12GraphicsCommandList::Dispatch Executes a command list from a thread group.
ID3D12GraphicsCommandList::DrawIndexedInstanced Draws indexed, instanced primitives.
ID3D12GraphicsCommandList::DrawInstanced Draws non-indexed, instanced primitives.
ID3D12GraphicsCommandList::EndEvent Not intended to be called directly.  Use the PIX event runtime to insert events into a command list.
ID3D12GraphicsCommandList::EndQuery Ends a running query.
ID3D12GraphicsCommandList::ExecuteBundle Executes a bundle.
ID3D12GraphicsCommandList::ExecuteIndirect Apps perform indirect draws/dispatches using the ExecuteIndirect method.
ID3D12GraphicsCommandList::IASetIndexBuffer Sets the view for the index buffer.
ID3D12GraphicsCommandList::IASetPrimitiveTopology Bind information about the primitive type, and data order that describes input data for the input assembler stage.
ID3D12GraphicsCommandList::IASetVertexBuffers Sets a CPU descriptor handle for the vertex buffers.
ID3D12GraphicsCommandList::OMSetBlendFactor Sets the blend factor that modulate values for a pixel shader, render target, or both.
ID3D12GraphicsCommandList::OMSetRenderTargets Sets CPU descriptor handles for the render targets and depth stencil.
ID3D12GraphicsCommandList::OMSetStencilRef Sets the reference value for depth stencil tests.
ID3D12GraphicsCommandList::Reset Resets a command list back to its initial state as if a new command list was just created.
ID3D12GraphicsCommandList::ResolveQueryData Extracts data from a query. ResolveQueryData works with all heap types (default, upload, and readback).  ResolveQueryData works with all heap types (default, upload, and readback). .
ID3D12GraphicsCommandList::ResolveSubresource Copy a multi-sampled resource into a non-multi-sampled resource.
ID3D12GraphicsCommandList::ResourceBarrier Notifies the driver that it needs to synchronize multiple accesses to resources.
ID3D12GraphicsCommandList::RSSetScissorRects Binds an array of scissor rectangles to the rasterizer stage.
ID3D12GraphicsCommandList::RSSetViewports Bind an array of viewports to the rasterizer stage of the pipeline.
ID3D12GraphicsCommandList::SetComputeRoot32BitConstant Sets a constant in the compute root signature.
ID3D12GraphicsCommandList::SetComputeRoot32BitConstants Sets a group of constants in the compute root signature.
ID3D12GraphicsCommandList::SetComputeRootConstantBufferView Sets a CPU descriptor handle for the constant buffer in the compute root signature.
ID3D12GraphicsCommandList::SetComputeRootDescriptorTable Sets a descriptor table into the compute root signature.
ID3D12GraphicsCommandList::SetComputeRootShaderResourceView Sets a CPU descriptor handle for the shader resource in the compute root signature.
ID3D12GraphicsCommandList::SetComputeRootSignature Sets the layout of the compute root signature.
ID3D12GraphicsCommandList::SetComputeRootUnorderedAccessView Sets a CPU descriptor handle for the unordered-access-view resource in the compute root signature.
ID3D12GraphicsCommandList::SetDescriptorHeaps Changes the currently bound descriptor heaps that are associated with a command list.
ID3D12GraphicsCommandList::SetGraphicsRoot32BitConstant Sets a constant in the graphics root signature.
ID3D12GraphicsCommandList::SetGraphicsRoot32BitConstants Sets a group of constants in the graphics root signature.
ID3D12GraphicsCommandList::SetGraphicsRootConstantBufferView Sets a CPU descriptor handle for the constant buffer in the graphics root signature.
ID3D12GraphicsCommandList::SetGraphicsRootDescriptorTable Sets a descriptor table into the graphics root signature.
ID3D12GraphicsCommandList::SetGraphicsRootShaderResourceView Sets a CPU descriptor handle for the shader resource in the graphics root signature.
ID3D12GraphicsCommandList::SetGraphicsRootSignature Sets the layout of the graphics root signature.
ID3D12GraphicsCommandList::SetGraphicsRootUnorderedAccessView Sets a CPU descriptor handle for the unordered-access-view resource in the graphics root signature.
ID3D12GraphicsCommandList::SetMarker Not intended to be called directly.  Use the PIX event runtime to insert events into a command list.
ID3D12GraphicsCommandList::SetPipelineState Sets all shaders and programs most of the fixed-function state of the graphics processing unit (GPU) pipeline.
ID3D12GraphicsCommandList::SetPredication Sets a rendering predicate.
ID3D12GraphicsCommandList::SOSetTargets Sets the stream output buffer views.

Remarks

This interface is new to D3D12, encapsulating much of the functionality of the ID3D11CommandList interface, and including the new functionality described in Rendering.

Examples

The D3D12nBodyGravity sample uses ID3D12GraphicsCommandList as follows:

Declare the pipeline objects.

D3D12_VIEWPORT m_viewport;
D3D12_RECT m_scissorRect;
ComPtr<IDXGISwapChain3> m_swapChain;
ComPtr<ID3D12Device> m_device;
ComPtr<ID3D12Resource> m_renderTargets[FrameCount];
ComPtr<ID3D12CommandAllocator> m_commandAllocator;
ComPtr<ID3D12CommandQueue> m_commandQueue;
ComPtr<ID3D12RootSignature> m_rootSignature;
ComPtr<ID3D12DescriptorHeap> m_rtvHeap;
ComPtr<ID3D12PipelineState> m_pipelineState;
ComPtr<ID3D12GraphicsCommandList> m_commandList;
UINT m_rtvDescriptorSize;

Populating command lists.

// Fill the command list with all the render commands and dependent state.
void D3D12nBodyGravity::PopulateCommandList()
{
    // Command list allocators can only be reset when the associated
    // command lists have finished execution on the GPU; apps should use
    // fences to determine GPU execution progress.
    ThrowIfFailed(m_commandAllocators[m_frameIndex]->Reset());

    // However, when ExecuteCommandList() is called on a particular command
    // list, that command list can then be reset at any time and must be before
    // re-recording.
    ThrowIfFailed(m_commandList->Reset(m_commandAllocators[m_frameIndex].Get(), m_pipelineState.Get()));

    // Set necessary state.
    m_commandList->SetPipelineState(m_pipelineState.Get());
    m_commandList->SetGraphicsRootSignature(m_rootSignature.Get());

    m_commandList->SetGraphicsRootConstantBufferView(RootParameterCB, m_constantBufferGS->GetGPUVirtualAddress() + m_frameIndex * sizeof(ConstantBufferGS));

    ID3D12DescriptorHeap* ppHeaps[] = { m_srvUavHeap.Get() };
    m_commandList->SetDescriptorHeaps(_countof(ppHeaps), ppHeaps);

    m_commandList->IASetVertexBuffers(0, 1, &m_vertexBufferView);
    m_commandList->IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_POINTLIST);
    m_commandList->RSSetScissorRects(1, &m_scissorRect);

    // Indicate that the back buffer will be used as a render target.
    m_commandList->ResourceBarrier(1, &CD3DX12_RESOURCE_BARRIER::Transition(m_renderTargets[m_frameIndex].Get(), D3D12_RESOURCE_STATE_PRESENT, D3D12_RESOURCE_STATE_RENDER_TARGET));

    CD3DX12_CPU_DESCRIPTOR_HANDLE rtvHandle(m_rtvHeap->GetCPUDescriptorHandleForHeapStart(), m_frameIndex, m_rtvDescriptorSize);
    m_commandList->OMSetRenderTargets(1, &rtvHandle, FALSE, nullptr);

    // Record commands.
    const float clearColor[] = { 0.0f, 0.0f, 0.1f, 0.0f };
    m_commandList->ClearRenderTargetView(rtvHandle, clearColor, 0, nullptr);

    // Render the particles.
    float viewportHeight = static_cast<float>(static_cast<UINT>(m_viewport.Height) / m_heightInstances);
    float viewportWidth = static_cast<float>(static_cast<UINT>(m_viewport.Width) / m_widthInstances);
    for (UINT n = 0; n < ThreadCount; n++)
    {
        const UINT srvIndex = n + (m_srvIndex[n] == 0 ? SrvParticlePosVelo0 : SrvParticlePosVelo1);

        D3D12_VIEWPORT viewport;
        viewport.TopLeftX = (n % m_widthInstances) * viewportWidth;
        viewport.TopLeftY = (n / m_widthInstances) * viewportHeight;
        viewport.Width = viewportWidth;
        viewport.Height = viewportHeight;
        viewport.MinDepth = D3D12_MIN_DEPTH;
        viewport.MaxDepth = D3D12_MAX_DEPTH;
        m_commandList->RSSetViewports(1, &viewport);

        CD3DX12_GPU_DESCRIPTOR_HANDLE srvHandle(m_srvUavHeap->GetGPUDescriptorHandleForHeapStart(), srvIndex, m_srvUavDescriptorSize);
        m_commandList->SetGraphicsRootDescriptorTable(RootParameterSRV, srvHandle);

        m_commandList->DrawInstanced(ParticleCount, 1, 0, 0);
    }

    m_commandList->RSSetViewports(1, &m_viewport);

    // Indicate that the back buffer will now be used to present.
    m_commandList->ResourceBarrier(1, &CD3DX12_RESOURCE_BARRIER::Transition(m_renderTargets[m_frameIndex].Get(), D3D12_RESOURCE_STATE_RENDER_TARGET, D3D12_RESOURCE_STATE_PRESENT));

    ThrowIfFailed(m_commandList->Close());
}

Refer to the Example Code in the D3D12 Reference.

Requirements

   
Target Platform Windows
Header d3d12.h

See Also

Core Interfaces

ID3D12CommandList

ID3D12GraphicsCommandList1