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

  • Article

Cette méthode utilise le GPU pour copier des données de texture entre deux emplacements. La source et la destination peuvent faire référence à des données de texture situées au sein d’une ressource de mémoire tampon ou d’une ressource de texture.

Syntaxe

void CopyTextureRegion(
  [in]           const D3D12_TEXTURE_COPY_LOCATION *pDst,
                 UINT                              DstX,
                 UINT                              DstY,
                 UINT                              DstZ,
  [in]           const D3D12_TEXTURE_COPY_LOCATION *pSrc,
  [in, optional] const D3D12_BOX                   *pSrcBox
);

Paramètres

[in] pDst

Type : const D3D12_TEXTURE_COPY_LOCATION*

Spécifie le D3D12_TEXTURE_COPY_LOCATION de destination. La sous-ressource référencée doit être à l’état D3D12_RESOURCE_STATE_COPY_DEST.

DstX

Type : UINT

Coordonnée x du coin supérieur gauche de la région de destination.

DstY

Type : UINT

Coordonnée y du coin supérieur gauche de la région de destination. Pour une sous-ressource 1D, cette valeur doit être égale à zéro.

DstZ

Type : UINT

Coordonnée z du coin supérieur gauche de la région de destination. Pour une sous-ressource 1D ou 2D, cette valeur doit être égale à zéro.

[in] pSrc

Type : const D3D12_TEXTURE_COPY_LOCATION*

Spécifie le D3D12_TEXTURE_COPY_LOCATION source. La sous-ressource référencée doit être à l’état D3D12_RESOURCE_STATE_COPY_SOURCE.

[in, optional] pSrcBox

Type : const D3D12_BOX*

Spécifie une D3D12_BOX facultative qui définit la taille de la texture source à copier.

Valeur de retour

None

Remarques

La zone source doit être dans la taille de la ressource source. Les décalages de destination (x, y et z) permettent à la zone source d’être décalée lors de l’écriture dans la ressource de destination ; toutefois, les dimensions de la zone source et les décalages doivent être dans la taille de la ressource. Si vous essayez de copier en dehors de la ressource de destination ou si vous spécifiez une zone source supérieure à la ressource source, le comportement de CopyTextureRegion n’est pas défini. Si vous avez créé un appareil qui prend en charge la couche de débogage, la sortie de débogage signale une erreur sur cet appel CopyTextureRegion non valide. Les paramètres non valides de CopyTextureRegion entraînent un comportement non défini et peuvent entraîner un rendu incorrect, une coupure, aucune copie ou même la suppression de l’appareil de rendu.

Si les ressources sont des mémoires tampons, toutes les coordonnées sont en octets ; si les ressources sont des textures, toutes les coordonnées sont en texels.

CopyTextureRegion effectue la copie sur le GPU (comme par memcpy le processeur). Par conséquent, les ressources source et de destination :

  • Il doit s’agir de sous-ressources différentes (bien qu’elles puissent provenir de la même ressource).
  • Doit avoir des DXGI_FORMATcompatibles (identiques ou du même groupe de types). Par exemple, une texture DXGI_FORMAT_R32G32B32_FLOAT peut être copiée dans une texture DXGI_FORMAT_R32G32B32_UINT, car ces deux formats se trouvent dans le groupe DXGI_FORMAT_R32G32B32_TYPELESS. CopyTextureRegion peut copier entre quelques types de format. Pour plus d’informations, consultez Formater la conversion à l’aide de Direct3D 10.1.
CopyTextureRegion prend uniquement en charge la copie ; il ne prend pas en charge d’étirement, de touche de couleur ou de fusion. CopyTextureRegion peut réinterpréter les données de ressource entre quelques types de format.

Notez que pour une mémoire tampon de gabarit de profondeur, les plans de profondeur et de gabarit sont des sous-ressources distinctes au sein de la mémoire tampon.

Pour copier une ressource entière, plutôt que simplement une région d’une sous-ressource, nous vous recommandons d’utiliser CopyResource à la place.

Note Si vous utilisez CopyTextureRegion avec une mémoire tampon de gabarit de profondeur ou une ressource multi-échantillonnée, vous devez copier l’intégralité du rectangle de sous-ressource. Dans ce cas, vous devez passer 0 aux paramètres DstX, DstY et DstZ et NULL au paramètre pSrcBox . En outre, les ressources sources et de destination, qui sont représentées par les paramètres pSrcResource et pDstResource , doivent avoir des valeurs de nombre d’échantillons identiques.
 
CopyTextureRegion peut être utilisé pour initialiser des ressources qui alias la même mémoire du tas. Pour plus d’informations, consultez CreatePlacedResource .

Exemple

L’extrait de code suivant copie la zone (située à (120 100),(200 220)) à partir d’une texture source dans la région (10 200), (90 140) dans une texture de destination. 
D3D12_BOX sourceRegion;
sourceRegion.left = 120;
sourceRegion.top = 100;
sourceRegion.right = 200;
sourceRegion.bottom = 220;
sourceRegion.front = 0;
sourceRegion.back = 1;

pCmdList -> CopyTextureRegion(pDestTexture, 10, 20, 0, pSourceTexture, &sourceRegion);

Notez que pour une texture 2D, les valeurs avant et arrière sont définies sur 0 et 1 respectivement.

Exemples

L’exemple HelloTriangle utilise ID3D12GraphicsCommandList ::CopyTextureRegion comme suit :

inline UINT64 UpdateSubresources(
    _In_ ID3D12GraphicsCommandList* pCmdList,
    _In_ ID3D12Resource* pDestinationResource,
    _In_ ID3D12Resource* pIntermediate,
    _In_range_(0,D3D12_REQ_SUBRESOURCES) UINT FirstSubresource,
    _In_range_(0,D3D12_REQ_SUBRESOURCES-FirstSubresource) UINT NumSubresources,
    UINT64 RequiredSize,
    _In_reads_(NumSubresources) const D3D12_PLACED_SUBRESOURCE_FOOTPRINT* pLayouts,
    _In_reads_(NumSubresources) const UINT* pNumRows,
    _In_reads_(NumSubresources) const UINT64* pRowSizesInBytes,
    _In_reads_(NumSubresources) const D3D12_SUBRESOURCE_DATA* pSrcData)
{
    // Minor validation
    D3D12_RESOURCE_DESC IntermediateDesc = pIntermediate->GetDesc();
    D3D12_RESOURCE_DESC DestinationDesc = pDestinationResource->GetDesc();
    if (IntermediateDesc.Dimension != D3D12_RESOURCE_DIMENSION_BUFFER || 
        IntermediateDesc.Width < RequiredSize + pLayouts[0].Offset || 
        RequiredSize > (SIZE_T)-1 || 
        (DestinationDesc.Dimension == D3D12_RESOURCE_DIMENSION_BUFFER && 
            (FirstSubresource != 0 || NumSubresources != 1)))
    {
        return 0;
    }
    
    BYTE* pData;
    HRESULT hr = pIntermediate->Map(0, NULL, reinterpret_cast<void**>(&pData));
    if (FAILED(hr))
    {
        return 0;
    }
    
    for (UINT i = 0; i < NumSubresources; ++i)
    {
        if (pRowSizesInBytes[i] > (SIZE_T)-1) return 0;
        D3D12_MEMCPY_DEST DestData = { pData + pLayouts[i].Offset, pLayouts[i].Footprint.RowPitch, pLayouts[i].Footprint.RowPitch * pNumRows[i] };
        MemcpySubresource(&DestData, &pSrcData[i], (SIZE_T)pRowSizesInBytes[i], pNumRows[i], pLayouts[i].Footprint.Depth);
    }
    pIntermediate->Unmap(0, NULL);
    
    if (DestinationDesc.Dimension == D3D12_RESOURCE_DIMENSION_BUFFER)
    {
        CD3DX12_BOX SrcBox( UINT( pLayouts[0].Offset ), UINT( pLayouts[0].Offset + pLayouts[0].Footprint.Width ) );
        pCmdList->CopyBufferRegion(
            pDestinationResource, 0, pIntermediate, pLayouts[0].Offset, pLayouts[0].Footprint.Width);
    }
    else
    {
        for (UINT i = 0; i < NumSubresources; ++i)
        {
            CD3DX12_TEXTURE_COPY_LOCATION Dst(pDestinationResource, i + FirstSubresource);
            CD3DX12_TEXTURE_COPY_LOCATION Src(pIntermediate, pLayouts[i]);
            pCmdList->CopyTextureRegion(&Dst, 0, 0, 0, &Src, nullptr);
        }
    }
    return RequiredSize;
}

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

Configuration requise

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

Voir aussi

CopyBufferRegion

ID3D12GraphicsCommandList