ID3D12GraphicsCommandList::Reset 메서드(d3d12.h)

아티클
08/23/2023

새 명령 목록이 방금 만들어진 것처럼 명령 목록을 초기 상태로 다시 설정합니다.

구문

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 반환 코드를 참조하세요.

설명

재설정을 사용하면 할당 없이 명령 목록 추적 구조를 다시 사용할 수 있습니다. ID3D12CommandAllocator::Reset과 달리, 명령 목록이 실행되는 동안에도 Reset을 호출할 수 있습니다. 일반적인 패턴은 명령 목록을 제출한 후, 즉시 재설정하여 할당된 메모리를 다른 명령 목록에 다시 사용하는 것입니다.

직접 명령 목록과 번들 모두에 Reset 을 사용할 수 있습니다.

Reset에서 입력으로 사용하는 명령 할당자는 한 번에 하나 이상의 기록 명령 목록과 연결할 수 있습니다. 할당자 유형, 직접 명령 목록 또는 번들은 생성되는 명령 목록의 형식과 일치해야 합니다.

번들이 리소스 힙을 지정하지 않으면 설명자 테이블이 바인딩되는 것을 변경할 수 없습니다. 어느 쪽이든 번들은 번들 내에서 리소스 힙을 변경할 수 없습니다. 번들에 대해 힙이 지정된 경우 힙은 호출하는 '부모' 명령 목록의 힙과 일치해야 합니다.

런타임 유효성 검사

앱이 Reset을 호출하기 전에 명령 목록이 "닫힌" 상태여야 합니다. 명령 목록이 "닫힌" 상태가 아니면 다시 설정이 실패합니다.

참고ID3D12GraphicsCommandList::Close 호출이 실패하면 명령 목록을 다시 설정할 수 없습니다. 재설정을 호출하면 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 참조의 예제 코드를 참조하세요.