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

Avertit le pilote qu’il doit synchroniser plusieurs accès aux ressources.

Syntaxe

void ResourceBarrier(
  [in] UINT                         NumBarriers,
  [in] const D3D12_RESOURCE_BARRIER *pBarriers
);

Paramètres

[in] NumBarriers

Type : UINT

Nombre de descriptions de barrières soumises.

[in] pBarriers

Type : const D3D12_RESOURCE_BARRIER*

Pointeur vers un tableau de descriptions de barrières.

Valeur de retour

None

Notes

Il existe trois types de descriptions de barrières :

• D3D12_RESOURCE_TRANSITION_BARRIER : les barrières de transition indiquent qu’un ensemble de sous-ressources passe entre différentes utilisations. L’appelant doit spécifier les utilisations avant et après des sous-ressources. L’indicateur D3D12_RESOURCE_BARRIER_ALL_SUBRESOURCES est utilisé pour effectuer la transition de toutes les sous-ressources d’une ressource en même temps.
• D3D12_RESOURCE_ALIASING_BARRIER : les barrières d’alias indiquent une transition entre les utilisations de deux ressources différentes qui ont des mappages dans le même tas. L’application peut spécifier les ressources before et after. Notez qu’une ou les deux ressources peuvent avoir la valeur NULL (ce qui indique qu’une ressource en mosaïque peut entraîner un alias).
• D3D12_RESOURCE_UAV_BARRIER : les barrières d’affichage d’accès non ordonnées indiquent que tous les accès par UAV (lecture ou écriture) à une ressource particulière doivent se terminer avant que les futurs accès par UAV (lecture ou écriture) puissent commencer. La ressource spécifiée peut être NULL. Il n’est pas nécessaire d’insérer une barrière UAV entre deux appels de dessin ou de distribution qui lisent uniquement un UAV. En outre, il n’est pas nécessaire d’insérer une barrière UAV entre deux appels de tirage ou de distribution qui écrivent sur le même UAV si l’application sait qu’il est sûr d’exécuter les accès UAV dans n’importe quel ordre. La ressource peut être NULL (ce qui indique que tout accès UAV peut nécessiter la barrière).

Quand ID3D12GraphicsCommandList::ResourceBarrier reçoit un tableau de descriptions de barrière de ressources, l’API se comporte comme si elle était appelée N fois (1 pour chaque élément de tableau), dans l’ordre spécifié. Les transitions doivent être regroupées dans un seul appel d’API dans la mesure du possible, en tant qu’optimisation des performances.

Pour obtenir une description des états d’utilisation dans utilisant une sous-ressource, consultez l’énumération D3D12_RESOURCE_STATES et la section Utilisation de barrières de ressources pour synchroniser les états de ressources dans Direct3D 12 .

Toutes les sous-ressources d’une ressource doivent être à l’état RENDER_TARGET, ou DEPTH_WRITE, pour les ressources de cibles de rendu/de gabarit de profondeur, respectivement, quand ID3D12GraphicsCommandList::D iscardResource est appelé.

Lorsqu’une mémoire tampon d’arrière-mémoire est présentée, elle doit être à l’état D3D12_RESOURCE_STATE_PRESENT. Si IDXGISwapChain1::P resent1 est appelé sur une ressource qui n’est pas dans l’état PRESENT, un avertissement de couche de débogage est émis.

Les bits d’utilisation des ressources sont regroupés en deux catégories , en lecture seule et en lecture/écriture.

Les bits d’utilisation suivants sont en lecture seule :

• D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER
• D3D12_RESOURCE_STATE_INDEX_BUFFER
• D3D12_RESOURCE_STATE_NON_PIXEL_SHADER_RESOURCE
• D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE
• D3D12_RESOURCE_STATE_INDIRECT_ARGUMENT
• D3D12_RESOURCE_STATE_COPY_SOURCE
• D3D12_RESOURCE_STATE_DEPTH_READ

Les bits d’utilisation suivants sont en lecture/écriture :

• D3D12_RESOURCE_STATE_UNORDERED_ACCESS
• D3D12_RESOURCE_STATE_DEPTH_WRITE

Les bits d’utilisation suivants sont en écriture seule :

• D3D12_RESOURCE_STATE_COPY_DEST
• D3D12_RESOURCE_STATE_RENDER_TARGET
• D3D12_RESOURCE_STATE_STREAM_OUT

Au maximum un bit d’écriture peut être défini. Si un bit d’écriture est défini, aucun bit de lecture ne peut être défini. Si aucun bit d’écriture n’est défini, un nombre quelconque de bits de lecture peut être défini.

À tout moment, une sous-ressource est dans un seul état (déterminé par un ensemble d’indicateurs). L’application doit s’assurer que les états sont mis en correspondance lors de l’exécution d’une séquence d’appels ResourceBarrier . En d’autres termes, les états avant et après dans les appels consécutifs à ResourceBarrier doivent être d’accord.

Pour effectuer la transition de toutes les sous-ressources au sein d’une ressource, l’application peut définir l’index de sous-ressource sur D3D12_RESOURCE_BARRIER_ALL_SUBRESOURCES, ce qui implique que toutes les sous-ressources sont modifiées.

Pour améliorer les performances, les applications doivent utiliser des barrières fractionnées ( reportez-vous à Synchronisation multi-moteur). Votre application doit également traiter par lot plusieurs transitions en un seul appel dans la mesure du possible.

Validation du runtime

Le runtime vérifie que les valeurs de type de barrière sont des membres valides de l’énumération D3D12_RESOURCE_BARRIER_TYPE .

En outre, le runtime vérifie les éléments suivants :

• Le pointeur de ressource n’est pas NULL.
• L’index de sous-ressource est valide
• Les états avant et après sont pris en charge par les indicateurs D3D12_RESOURCE_BINDING_TIER et D3D12_RESOURCE_FLAGS de la ressource.
• Les bits réservés dans les masques d’état ne sont pas définis.
• Les états avant et après sont différents.
• L’ensemble de bits dans les états avant et après sont valides.
• Si le bit D3D12_RESOURCE_STATE_RESOLVE_SOURCE est défini, le nombre d’échantillons de ressources doit être supérieur à 1.
• Si le bit D3D12_RESOURCE_STATE_RESOLVE_DEST est défini, le nombre d’échantillons de ressources doit être égal à 1.

Pour les barrières d’alias, le runtime vérifie que, si l’un ou l’autre pointeur de ressource n’a pas la valeur NULL, il fait référence à une ressource en mosaïque.

Pour les barrières UAV, le runtime vérifie que, si la ressource n’est pas NULL, l’indicateur de liaison D3D12_RESOURCE_STATE_UNORDERED_ACCESS est défini.

L’échec de la validation entraîne le retour de E_INVALIDARG id3D12GraphicsCommandList::Close .

Couche de débogage

La couche de débogage émet normalement des erreurs en cas d’échec de la validation du runtime :

• Si une transition de sous-ressource dans une liste de commandes n’est pas cohérente avec les transitions précédentes dans la même liste de commandes.
• Si une ressource est utilisée sans appeler d’abord ResourceBarrier pour mettre la ressource dans un état correct.
• Si une ressource est illégalement liée à la lecture et à l’écriture en même temps.
• Si les états avant passés à ResourceBarrier ne correspondent pas aux états après des appels précédents à ResourceBarrier, y compris le cas d’alias.

Alors que la couche de débogage tente de valider les règles d’exécution, elle fonctionne de manière conservatrice de sorte que les erreurs de couche de débogage sont des erreurs réelles et, dans certains cas, des erreurs réelles peuvent ne pas produire d’erreurs de couche de débogage.

La couche de débogage émet des avertissements dans les cas suivants :

• Tous les cas où la couche de débogage D3D12 émet des avertissements pour ID3D12GraphicsCommandList::ResourceBarrier.
• Si une mémoire tampon de profondeur est utilisée en mode non lecture seule alors que la ressource a le bit d’utilisation D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE défini.

Exemples

L’exemple D3D12HelloTriangle utilise ID3D12GraphicsCommandList::ResourceBarrier 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.

Spécifications

Plateforme cible	Windows
En-tête	d3d12.h
Bibliothèque	D3d12.lib
DLL	D3d12.dll

Voir aussi

ID3D12GraphicsCommandList

Utilisation de barrières de ressources pour synchroniser les états des ressources dans Direct3D 12