Método ID3D12GraphicsCommandList::Reset (d3d12.h)

Artigo
08/23/2023

Redefine uma lista de comandos de volta ao estado inicial como se uma nova lista de comandos tivesse sido criada.

Sintaxe

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

Parâmetros

[in] pAllocator

Tipo: ID3D12CommandAllocator*

Um ponteiro para o objeto ID3D12CommandAllocator do qual o dispositivo cria listas de comandos.

[in, optional] pInitialState

Tipo: ID3D12PipelineState*

Um ponteiro para o objeto ID3D12PipelineState que contém o estado inicial do pipeline para a lista de comandos. Isso é opcional e pode ser NULL. Se FOR NULL, o runtime definirá um estado de pipeline inicial fictício para que os drivers não precisem lidar com o estado indefinido. A sobrecarga para isso é baixa, especialmente para uma lista de comandos, para a qual o custo geral da gravação da lista de comandos provavelmente reduz o custo de uma configuração de estado inicial. Portanto, há pouco custo em não definir o parâmetro de estado inicial do pipeline se não for conveniente.

Para pacotes por outro lado, pode fazer mais sentido tentar definir o parâmetro de estado inicial, pois os pacotes provavelmente são menores no geral e podem ser reutilizados com frequência.

Retornar valor

Tipo: HRESULT

Retorna S_OK se tiver êxito; caso contrário, retorna um dos seguintes valores:

E_FAIL se a lista de comandos não estivesse no estado "fechado" quando a chamada redefinir foi feita ou o limite por dispositivo teria sido excedido.
E_OUTOFMEMORY se o sistema operacional ficou sem memória.
E_INVALIDARG se o alocador estiver sendo usado com outra lista de comandos no estado "gravação" ou se o alocador especificado tiver sido criado com o tipo errado.

Consulte Códigos de retorno do Direct3D 12 para obter outros valores retornados possíveis.

Comentários

Usando Redefinir, você pode reutilização de estruturas de acompanhamento de lista de comandos sem alocações. Ao contrário de ID3D12CommandAllocator::Reset, você pode chamar Redefinir enquanto a lista de comandos ainda está sendo executada. Um padrão típico é enviar uma lista de comandos e, em seguida, redefini-la imediatamente para reutilizar a memória alocada para outra lista de comandos.

Você pode usar Redefinir para listas de comandos diretas e pacotes.

O alocador de comandos que Redefinir usa como entrada pode ser associado a não mais do que uma lista de comandos de gravação por vez. O tipo de alocador, lista de comandos diretos ou pacote, deve corresponder ao tipo de lista de comandos que está sendo criada.

Se um pacote não especificar um heap de recursos, ele não poderá fazer alterações às quais tabelas de descritor estão associadas. De qualquer forma, os pacotes não podem alterar o heap de recursos dentro do pacote. Se um heap for especificado para um pacote, o heap deverá corresponder ao heap da lista de comandos 'pai' de chamada.

Validação de runtime

Antes que um aplicativo chame Redefinir, a lista de comandos deve estar no estado "fechado". A redefinição falhará se a lista de comandos não estiver no estado "fechado".

Nota Se uma chamada para ID3D12GraphicsCommandList::Close falhar, a lista de comandos nunca poderá ser redefinida. Chamar Redefinir resultará no mesmo erro retornado que ID3D12GraphicsCommandList::Close retornou.

Depois que Redefinir for bem-sucedida, a lista de comandos será deixada no estado "gravação". A redefinição falhará se isso fizer com que o limite máximo de lista de comandos de gravação simultânea, especificado na criação do dispositivo, seja excedido.

Os aplicativos devem especificar um alocador de lista de comandos. O runtime garantirá que um alocador nunca esteja associado a mais de uma lista de comandos de gravação ao mesmo tempo.

A redefinição falha para pacotes referenciados por uma lista de comandos ainda não enviada.

Camada de depuração

A camada de depuração também acompanhará o progresso da GPU (unidade de processamento gráfico) e emitirá um erro se não puder provar que não há execuções pendentes da lista de comandos.

Exemplos

O exemplo D3D12HelloTriangle usa ID3D12GraphicsCommandList::Reset da seguinte maneira:

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

Consulte Código de exemplo na referência D3D12.