ID3D12GraphicsCommandList::Reset-Methode (d3d12.h)

Artikel
02/26/2024

Setzt eine Befehlsliste wieder in ihren Anfangszustand 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 Laufzeit einen anfänglichen Pipelinestatus als Dummy fest, sodass Treiber sich nicht mit dem undefinierten Zustand befassen 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änglichzustandseinstellung in den Schatten stellen. Es fallen also geringe Kosten an, wenn sie den anfänglichen Parameter für den Pipelinezustand nicht festlegen, wenn dies nicht bequem ist.

Für Bundles auf der anderen Seite kann es sinnvoller sein, den Anfänglichzustandsparameter festzulegen, da Bundles insgesamt wahrscheinlich 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 durchgeführt wurde, oder wenn der Grenzwert pro Gerät überschritten worden wäre.
E_OUTOFMEMORY , wenn auf dem Betriebssystem nicht genügend Arbeitsspeicher vorhanden ist.
E_INVALIDARG , wenn die Zuweisung derzeit mit einer anderen Befehlsliste im Aufzeichnungszustand verwendet wird oder wenn die angegebene Zuweisung 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 zugeordneten 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 akzeptiert, kann nicht mehr als einer Aufzeichnungsbefehlsliste gleichzeitig zugeordnet werden. Der Zuweisungstyp, 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 wird.

Nach dem erfolgreichen Zurücksetzen verbleibt die Befehlsliste im Aufzeichnungszustand. Das Zurücksetzen schlägt fehl, wenn die maximale Beschränkung der Befehlsliste für die gleichzeitige Aufzeichnung, die bei der Geräteerstellung angegeben wird, überschritten würde.

Apps müssen eine Befehlslistenzuweisung angeben. Die Runtime stellt sicher, dass eine Zuweisung niemals mehr als einer Aufzeichnungsbefehlsliste gleichzeitig zugeordnet 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 Grafikverarbeitungseinheit (Graphics Processing Unit, GPU) und gibt einen Fehler aus, wenn sie nicht nachweisen kann, dass keine ausstehenden Ausführungen der Befehlsliste vorhanden sind.

Beispiele

Im D3D12HelloTriangle-Beispiel wird ID3D12GraphicsCommandList::Reset wie folgt verwendet:

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

Weitere Informationen finden Sie unter Beispielcode in der D3D12-Referenz.