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

Artigo
06/27/2024

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 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 do pipeline inicial 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.

Valor de retorno

Tipo: HRESULT

Retorna S_OK se bem-sucedido; caso contrário, retorna um dos seguintes valores:

E_FAIL se a lista de comandos não estava 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 de retorno possíveis.

Observações

Usando Redefinir, você pode reutilizá-la sem alocações. Ao contrário de ID3D12CommandAllocator::Reset, você pode chamar Redefinir enquanto a lista de comandos ainda está sendo executada.

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

O alocador de comandos passado para Redefinir não pode ser associado a nenhuma outra lista de comandos de gravação no momento. O tipo de alocador, lista de comandos direta 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 as 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 do runtime do

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

Observação 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 retornado.

Depois que Redefinir for bem-sucedida, a lista de comandos será deixada no estado "gravação". Redefinir 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.

de Redefinição falha em 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 node referência D3D12.

Requisitos

Requisito	Valor
da Plataforma de Destino	Windows
cabeçalho	d3d12.h
biblioteca	D3d12.lib
de DLL	D3d12.dll

Consulte também

ID3D12CommandAllocator::Reset

ID3D12Device::CreateCommandList

ID3D12GraphicsCommandList

Compartilhar via