ID3D12GraphicsCommandList::Reset-Methode (d3d12.h)

Artikel
06/27/2024

Setzt eine Befehlsliste auf den 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. Wenn NULL, legt die Laufzeit einen dummen anfänglichen Pipelinestatus fest, sodass Treiber keinen nicht definierten Zustand behandeln müssen. Der Aufwand für dies ist niedrig, insbesondere für eine Befehlsliste, für die die Gesamtkosten für die Aufzeichnung der Befehlsliste wahrscheinlich die Kosten einer Erstzustandseinstellung zwergt. Es gibt also wenig Kosten, um den Parameter für den anfänglichen Pipelinestatus nicht festzulegen, wenn er nicht bequem ist.

Für Bundles ist es möglicherweise sinnvoller, den anfänglichen Zustandsparameter festzulegen, da Bündel insgesamt wahrscheinlich kleiner sind und häufig wiederverwendet werden können.

Rückgabewert

Typ: HRESULT-

Gibt S_OK zurück, wenn dies erfolgreich ist; andernfalls gibt einen der folgenden Werte zurück:

E_FAIL, wenn sich die Befehlsliste nicht im Zustand "geschlossen" befand, als die Zurücksetzen Anrufs durchgeführt wurde oder die Grenze pro Gerät überschritten wurde.
E_OUTOFMEMORY, wenn das Betriebssystem nicht genügend Arbeitsspeicher hat.
E_INVALIDARG, wenn der Allocator derzeit mit einer anderen Befehlsliste im Zustand "Aufzeichnung" verwendet wird oder ob der angegebene Allocator mit dem falschen Typ erstellt wurde.

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

Bemerkungen

Mit Zurücksetzenkönnen Sie die Nachverfolgungsstrukturen der Befehlsliste ohne Zuordnungen erneut verwenden. Im Gegensatz zu ID3D12CommandAllocator::Resetkönnen Sie Reset aufrufen, während die Befehlsliste noch ausgeführt wird.

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

Der An Zurücksetzen übergebene Befehlsverteiler kann keiner anderen Derzeit aufgezeichneten Befehlsliste zugeordnet werden. Der Zuweisungstyp, die direkte Befehlsliste oder das Bündel muss mit dem Typ der zu erstellenden Befehlsliste übereinstimmen.

Wenn ein Bündel keinen Ressourcenhap angibt, kann er keine Änderungen daran vornehmen, an welche Deskriptortabellen gebunden sind. Auf beide Weise können Bündel den Ressourcen heap innerhalb des Bundles nicht ändern. Wenn für ein Bundle ein Heap angegeben ist, muss der Heap mit dem heap der aufrufenden Befehlsliste "übergeordnete" übereinstimmen.

Laufzeitüberprüfung

Bevor eine App Resetaufruft, muss sich die Befehlsliste im Zustand "geschlossen" befinden. 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 Zurücksetzen führt zu demselben Fehler, der zurückgegeben wird, ID3D12GraphicsCommandList::Close zurückgegeben wurde.

Nachdem Zurücksetzen erfolgreich ist, bleibt die Befehlsliste im Zustand "Aufzeichnung" übrig. Zurücksetzen schlägt fehl, wenn der maximale Grenzwert für gleichzeitig aufgezeichnete Befehlslisten, die bei der Geräteerstellung angegeben wird, überschritten wird.

Apps müssen einen Befehlslisten-Allocator angeben. Die Laufzeit stellt sicher, dass ein Zuweisungsmodul nie gleichzeitig mehreren Aufzeichnungsbefehlslisten zugeordnet ist.

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

Debugebene

Die Debugebene verfolgt außerdem den Fortschritt der Grafikverarbeitungseinheit (GPU) 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.