Metodo ID3D12GraphicsCommandList::Reset (d3d12.h)

Articolo
02/29/2024

Reimposta un elenco di comandi allo stato iniziale come se fosse stato appena creato un nuovo elenco di comandi.

Sintassi

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

Parametri

[in] pAllocator

Tipo: ID3D12CommandAllocator*

Puntatore all'oggetto ID3D12CommandAllocator da cui il dispositivo crea elenchi di comandi.

[in, optional] pInitialState

Tipo: ID3D12PipelineState*

Puntatore all'oggetto ID3D12PipelineState contenente lo stato della pipeline iniziale per l'elenco di comandi. Questo è facoltativo e può essere NULL. Se NULL, il runtime imposta uno stato iniziale fittizio della pipeline in modo che i driver non devono gestire lo stato non definito. Il sovraccarico per questo è basso, in particolare per un elenco di comandi, per il quale il costo complessivo della registrazione dell'elenco di comandi probabilmente riduce il costo di un'impostazione di stato iniziale. Pertanto, non è necessario impostare il parametro dello stato della pipeline iniziale se non è pratico.

Per i bundle, invece, potrebbe essere più opportuno provare a impostare il parametro di stato iniziale poiché i bundle sono probabilmente più piccoli e possono essere riutilizzati di frequente.

Valore restituito

Tipo: HRESULT

Restituisce S_OK se ha esito positivo; in caso contrario, restituisce uno dei valori seguenti:

E_FAIL se l'elenco di comandi non era nello stato "chiuso" quando è stata effettuata la chiamata Di reimpostazione o il limite per dispositivo sarebbe stato superato.
E_OUTOFMEMORY se il sistema operativo ha esaurito la memoria.
E_INVALIDARG se l'allocatore è attualmente in uso con un altro elenco di comandi nello stato "registrazione" o se l'allocatore specificato è stato creato con il tipo errato.

Per altri valori restituiti, vedere Codici restituiti Direct3D 12 .

Commenti

Usando Reimposta, è possibile riutilizzare le strutture di rilevamento dell'elenco di comandi senza allocazioni. A differenza di ID3D12CommandAllocator::Reset, è possibile chiamare Reimposta mentre l'elenco di comandi è ancora in esecuzione. Un modello tipico consiste nell'inviare un elenco di comandi e quindi reimpostarlo immediatamente per riutilizzare la memoria allocata per un altro elenco di comandi.

È possibile usare Reimposta per elenchi di comandi diretti e bundle.

L'allocatore di comando che Reimposta accetta come input può essere associato a non più di un elenco di comandi di registrazione alla volta. Il tipo di allocatore, l'elenco di comandi diretti o il bundle, devono corrispondere al tipo di elenco di comandi creato.

Se un bundle non specifica un heap delle risorse, non può apportare modifiche alle tabelle descrittori associate. In entrambi i casi, i bundle non possono modificare l'heap della risorsa all'interno del bundle. Se viene specificato un heap per un bundle, l'heap deve corrispondere all'heap chiamante dell'heap dell'elenco di comandi 'padre'.

Convalida del runtime

Prima che un'app chiami Reimposta, l'elenco di comandi deve trovarsi nello stato "chiuso". La reimpostazione avrà esito negativo se l'elenco di comandi non è nello stato "chiuso".

Nota Se una chiamata a ID3D12GraphicsCommandList::Close ha esito negativo, l'elenco di comandi non può mai essere reimpostato. La chiamata a Reimpostazione genera lo stesso errore restituito da ID3D12GraphicsCommandList::Close restituito.

Dopo aver completato la reimpostazione , l'elenco dei comandi viene lasciato nello stato "registrazione". La reimpostazione avrà esito negativo se il limite massimo di elenco comandi di registrazione simultanea, specificato alla creazione del dispositivo, verrà superato.

Le app devono specificare un allocatore dell'elenco di comandi. Il runtime garantisce che un allocatore non sia mai associato a più di un elenco di comandi di registrazione contemporaneamente.

La reimpostazione ha esito negativo per i bundle a cui fa riferimento un elenco di comandi non ancora inviato.

Livello di debug

Il livello di debug tiene traccia anche dello stato di avanzamento dell'unità di elaborazione grafica (GPU) e genera un errore se non riesce a dimostrare che non sono presenti esecuzioni in sospeso dell'elenco di comandi.

Esempio

L'esempio D3D12HelloTriangle usa ID3D12GraphicsCommandList::Reset come indicato di seguito:

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

Vedere Codice di esempio nel riferimento D3D12.