ID3D12GraphicsCommandList::Reset-Methode (d3d12.h)

Artikel
08/23/2023

Setzt eine Befehlsliste wieder auf den ursprünglichen Zustand zurück, als ob gerade eine neue Befehlsliste erstellt wurde.

Syntax

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

Parameter

[in] pAllocator

Typ: ID3D12CommandAllocator*

Ein Zeiger auf das ID3D12CommandAllocator-Objekt , aus dem das Gerät Befehlslisten erstellt.

[in, optional] pInitialState

Typ: ID3D12PipelineState*

Ein Zeiger auf das ID3D12PipelineState-Objekt , das den anfänglichen Pipelinestatus für die Befehlsliste enthält. Dies ist optional und kann NULL sein. Bei NULL legt die Runtime einen Anfangsstatus der Pipeline für Dummy fest, sodass treiber nicht mit dem nicht definierten Zustand umgehen müssen. Der Aufwand hierfür ist gering, insbesondere für eine Befehlsliste, bei der die Gesamtkosten für die Aufzeichnung der Befehlsliste wahrscheinlich die Kosten einer anfänglichen Zustandseinstellung in den Schatten stellen. Es fallen also nur geringe Kosten an, wenn der anfängliche Pipelinezustandsparameter nicht festgelegt wird, wenn dies nicht bequem ist.

Für Bundles auf der anderen Seite kann es sinnvoller sein, zu versuchen, den anfänglichen Zustandsparameter festzulegen, da Bundles wahrscheinlich insgesamt kleiner sind und häufig wiederverwendet werden können.

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK zurück. Gibt andernfalls einen der folgenden Werte zurück:

E_FAIL , wenn sich die Befehlsliste nicht im Zustand "geschlossen" befand, als der Reset-Aufruf ausgeführt wurde, oder wenn der Grenzwert pro Gerät überschritten wurde.
E_OUTOFMEMORY , wenn dem Betriebssystem der Arbeitsspeicher ausging.
E_INVALIDARG , wenn der Zuweisungsgeber derzeit mit einer anderen Befehlsliste im Status "Aufzeichnung" verwendet wird oder wenn der angegebene Zuordnungsgeber mit dem falschen Typ erstellt wurde.

Weitere mögliche Rückgabewerte finden Sie unter Direct3D 12-Rückgabecodes .

Hinweise

Mithilfe von Zurücksetzen können Sie Befehlslistennachverfolgungsstrukturen ohne Zuordnungen wiederverwenden. Im Gegensatz zu ID3D12CommandAllocator::Reset können Sie Reset aufrufen, während die Befehlsliste noch ausgeführt wird. Ein typisches Muster besteht darin, eine Befehlsliste zu übermitteln und dann sofort zurückzusetzen, um den zugewiesenen Arbeitsspeicher für eine andere Befehlsliste wiederzuverwenden.

Sie können Zurücksetzen sowohl für direkte Befehlslisten als auch für Bundles verwenden.

Die Befehlszuweisung, die Reset als Eingabe übernimmt, kann nicht mehr als einer Aufzeichnungsbefehlsliste gleichzeitig zugeordnet werden. Der Zuordnungstyp, die direkte Befehlsliste oder das Bündel, muss mit dem Typ der Befehlsliste übereinstimmen, die erstellt wird.

Wenn ein Bundle keinen Ressourcenheap angibt, kann es keine Änderungen daran vornehmen, an welche Deskriptortabellen gebunden sind. In beiden Richtungen können Bundles den Ressourcenheap innerhalb des Bundles nicht ändern. Wenn ein Heap für ein Bundle angegeben wird, muss der Heap mit dem Heap der aufrufenden "parent"-Befehlsliste übereinstimmen.

Laufzeitüberprüfung

Bevor eine App Reset aufruft, muss sich die Befehlsliste im Zustand "geschlossen" befinden. Das Zurücksetzen schlägt fehl, wenn sich die Befehlsliste nicht im Zustand "geschlossen" befindet.

Hinweis Wenn ein Aufruf von ID3D12GraphicsCommandList::Close fehlschlägt, kann die Befehlsliste nie zurückgesetzt werden. Das Aufrufen von Reset führt dazu, dass derselbe Fehler zurückgegeben wird, der ID3D12GraphicsCommandList::Close zurückgegeben wurde.

Nachdem das Zurücksetzen erfolgreich war, wird die Befehlsliste im Status "Aufzeichnung" belassen. Beim Zurücksetzen tritt ein Fehler auf, wenn die maximale Begrenzung der Befehlsliste für gleichzeitige Aufzeichnungen, die bei der Geräteerstellung angegeben wird, überschritten wird.

Apps müssen eine Befehlslistenzuordnung angeben. Die Runtime stellt sicher, dass ein Zuweisungsmodul nie mit mehr als einer Aufzeichnungsbefehlsliste gleichzeitig verknüpft ist.

Das Zurücksetzen schlägt für Bundles fehl, auf die von einer noch nicht übermittelten Befehlsliste verwiesen wird.

Debugebene

Die Debugebene verfolgt auch den Fortschritt der Gpu (Graphics Processing Unit) nach und gibt einen Fehler aus, wenn nicht nachgewiesen werden kann, dass keine ausstehenden Ausführungen der Befehlsliste vorhanden sind.

Beispiele

Das D3D12HelloTriangle-Beispiel verwendet ID3D12GraphicsCommandList::Reset wie folgt:

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

Siehe Beispielcode in der D3D12-Referenz.