ID3D12GraphicsCommandList：：Reset 方法 (d3d12.h)

發行項
03/05/2024

將命令清單重設為其初始狀態，就像剛建立新的命令清單一樣。

語法

HRESULT Reset(
  [in]           ID3D12CommandAllocator *pAllocator,
  [in, optional] ID3D12PipelineState    *pInitialState
);

參數

[in] pAllocator

類型： ID3D12CommandAllocator*

裝置從中建立命令清單的 ID3D12CommandAllocator 物件的指標。

[in, optional] pInitialState

類型： ID3D12PipelineState*

ID3D12PipelineState 物件的指標，其中包含命令清單的初始管線狀態。這是選擇性的，而且可以是 NULL。如果為 NULL，運行時間會設定虛擬初始管線狀態，讓驅動程式不需要處理未定義的狀態。這的額外負荷很低，特別是對於命令清單而言，錄製命令清單的整體成本可能會使一個初始狀態設定的成本加大。因此，如果初始管線狀態參數不方便，則不需要設定初始管線狀態參數。

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

傳回值

類型： HRESULT

如果成功，則傳回S_OK;否則，會傳回下列其中一個值：

E_FAIL 如果命令清單不是在進行重設呼叫時處於「已關閉」狀態，或超過每個裝置的限制。
如果操作系統記憶體不足，E_OUTOFMEMORY。
E_INVALIDARG 如果配置器目前正與處於「錄製」狀態的另一個命令清單搭配使用，或是指定的配置器是以錯誤類型建立的。

如需其他可能的傳回值，請參閱 Direct3D 12 傳回碼。

備註

藉由使用 Reset，您可以重複使用命令清單追蹤結構，而不需要任何配置。不同於 ID3D12CommandAllocator：：Reset，您可以在命令清單仍在執行時呼叫 Reset 。典型的模式是提交命令清單，然後立即重設它，以重複使用配置給另一個命令清單的記憶體。

您可以針對直接命令清單和套件組合使用 Reset 。

Reset 做為輸入的命令配置器一次不能與一個以上的錄製命令清單相關聯。配置器類型、直接命令清單或套件組合必須符合所建立的命令清單類型。

如果套件組合未指定資源堆積，就無法變更系結描述元數據表。不論是哪一種方式，套件組合都無法變更套件組合內的資源堆積。如果為套件組合指定堆積，堆積必須符合呼叫的『parent』命令清單堆積。

運行時間驗證

在應用程式呼叫 Reset 之前，命令清單必須處於「已關閉」狀態。如果命令清單不是處於「已關閉」狀態，重設將會失敗。

注意如果呼叫 ID3D12GraphicsCommandList：：Close 失敗，則永遠無法重設命令清單。呼叫 Reset 會導致 傳回 ID3D12GraphicsCommandList：：Close 傳回的相同錯誤。

重設成功之後，命令清單會保持「錄製」狀態。如果重設會導致超過裝置建立時所指定的同時錄製命令清單限制上限，重設將會失敗。

應用程式必須指定命令清單配置器。運行時間可確保配置器永遠不會同時與多個錄製命令清單相關聯。

尚未提交的命令清單所參考的套件組合重設失敗。

偵錯層

偵錯層也會追蹤 GPU) 進度 (圖形處理單位，如果無法證明命令列表沒有未完成的執行，就會發出錯誤。

範例

D3D12HelloTriangle 範例使用 ID3D12GraphicsCommandList：：Reset，如下所示：

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;

void D3D12HelloTriangle::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_commandAllocator->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_commandAllocator.Get(), m_pipelineState.Get()));

    // Set necessary state.
    m_commandList->SetGraphicsRootSignature(m_rootSignature.Get());
    m_commandList->RSSetViewports(1, &m_viewport);
    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.2f, 0.4f, 1.0f };
    m_commandList->ClearRenderTargetView(rtvHandle, clearColor, 0, nullptr);
    m_commandList->IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);
    m_commandList->IASetVertexBuffers(0, 1, &m_vertexBufferView);
    m_commandList->DrawInstanced(3, 1, 0, 0);

    // 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());
}

請參閱 D3D12 參考中的範例程式代碼。