ID3D12GraphicsCommandList ::Reset, méthode (d3d12.h)

Article
02/29/2024

Réinitialise une liste de commandes à son état initial comme si une nouvelle liste de commandes venait d’être créée.

Syntaxe

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

Paramètres

[in] pAllocator

Type : ID3D12CommandAllocator*

Pointeur vers l’objet ID3D12CommandAllocator à partir duquel l’appareil crée des listes de commandes.

[in, optional] pInitialState

Type : ID3D12PipelineState*

Pointeur vers l’objet ID3D12PipelineState qui contient l’état initial du pipeline pour la liste de commandes. Cette option est facultative et peut avoir la valeur NULL. Si la valeur est NULL, le runtime définit un état de pipeline initial factice afin que les pilotes n’aient pas à gérer l’état non défini. La surcharge est faible, en particulier pour une liste de commandes, pour laquelle le coût global d’enregistrement de la liste de commandes dépasse probablement le coût d’un paramètre d’état initial. Il est donc peu coûteux de ne pas définir le paramètre d’état du pipeline initial si ce n’est pas pratique.

En revanche, pour les offres groupées, il peut être plus judicieux d’essayer de définir le paramètre d’état initial, car les offres groupées sont probablement plus petites dans l’ensemble et peuvent être réutilisées fréquemment.

Valeur retournée

Type : HRESULT

Retourne S_OK en cas de réussite ; Dans le cas contraire, retourne l’une des valeurs suivantes :

E_FAIL si la liste de commandes n’était pas à l’état « fermé » au moment de l’appel de réinitialisation ou si la limite par appareil aurait été dépassée.
E_OUTOFMEMORY si le système d’exploitation est à court de mémoire.
E_INVALIDARG si l’allocateur est actuellement utilisé avec une autre liste de commandes à l’état « enregistrement » ou si l’utilitaire spécifié a été créé avec le type incorrect.

Pour obtenir d’autres valeurs de retour possibles, consultez Codes de retour Direct3D 12 .

Remarques

À l’aide de La réinitialisation, vous pouvez réutiliser les structures de suivi de liste de commandes sans aucune allocation. Contrairement à ID3D12CommandAllocator ::Reset, vous pouvez appeler Réinitialiser pendant que la liste de commandes est toujours en cours d’exécution. Un modèle classique consiste à envoyer une liste de commandes, puis à la réinitialiser immédiatement pour réutiliser la mémoire allouée pour une autre liste de commandes.

Vous pouvez utiliser Réinitialiser pour les listes de commandes directes et les offres groupées.

L’allocateur de commandes que la réinitialisation prend en tant qu’entrée ne peut pas être associé à plusieurs listes de commandes d’enregistrement à la fois. Le type d’utilitaire, liste de commandes directes ou bundle, doit correspondre au type de liste de commandes en cours de création.

Si un bundle ne spécifie pas de tas de ressources, il ne peut pas apporter de modifications auxquelles les tables de descripteurs sont liées. Quoi qu’il en soit, les offres groupées ne peuvent pas modifier le tas de ressources au sein de l’offre groupée. Si un tas est spécifié pour un bundle, le tas doit correspondre au tas de la liste de commandes « parent » appelante.

Validation du runtime

Avant qu’une application appelle Réinitialiser, la liste de commandes doit être à l’état « fermé ». La réinitialisation échoue si la liste de commandes n’est pas à l’état « fermé ».

Note Si un appel à ID3D12GraphicsCommandList ::Close échoue, la liste de commandes ne peut jamais être réinitialisée. L’appel de la réinitialisation entraîne le retour de la même erreur que id3D12GraphicsCommandList ::Close retourné.

Une fois la réinitialisation réussie, la liste de commandes reste à l’état « enregistrement ». La réinitialisation échoue si elle entraîne le dépassement de la limite maximale de liste de commandes d’enregistrement simultané, qui est spécifiée lors de la création de l’appareil.

Les applications doivent spécifier un allocateur de liste de commandes. Le runtime garantit qu’un allocator n’est jamais associé à plusieurs listes de commandes d’enregistrement en même temps.

La réinitialisation échoue pour les offres groupées référencées par une liste de commandes non encore envoyée.

Couche Debug

La couche de débogage suit également la progression de l’unité de traitement graphique (GPU) et génère une erreur si elle ne peut pas prouver qu’il n’y a pas d’exécutions en suspens de la liste de commandes.

Exemples

L’exemple D3D12HelloTriangle utilise ID3D12GraphicsCommandList ::Reset comme suit :

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

Consultez l’exemple de code dans la référence D3D12.