Método ID3D12GraphicsCommandList::CopyTextureRegion (d3d12.h)

  • Artículo

Este método usa la GPU para copiar datos de textura entre dos ubicaciones. Tanto el origen como el destino pueden hacer referencia a los datos de textura ubicados en un recurso de búfer o en un recurso de textura.

Sintaxis

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

Parámetros

[in] pDst

Tipo: const D3D12_TEXTURE_COPY_LOCATION*

Especifica el D3D12_TEXTURE_COPY_LOCATION de destino. El subrecurso al que se hace referencia debe estar en estado D3D12_RESOURCE_STATE_COPY_DEST.

DstX

Tipo: UINT

Coordenada x de la esquina superior izquierda de la región de destino.

DstY

Tipo: UINT

Coordenada y de la esquina superior izquierda de la región de destino. Para un subrecurso 1D, debe ser cero.

DstZ

Tipo: UINT

Coordenada z de la esquina superior izquierda de la región de destino. Para un subrecurso 1D o 2D, debe ser cero.

[in] pSrc

Tipo: const D3D12_TEXTURE_COPY_LOCATION*

Especifica el D3D12_TEXTURE_COPY_LOCATION de origen. El subrecurso al que se hace referencia debe estar en estado D3D12_RESOURCE_STATE_COPY_SOURCE.

[in, optional] pSrcBox

Tipo: const D3D12_BOX*

Especifica un D3D12_BOX opcional que establece el tamaño de la textura de origen que se va a copiar.

Valor devuelto

None

Observaciones

El cuadro de origen debe estar dentro del tamaño del recurso de origen. Los desplazamientos de destino , (x, y y z), permiten que el cuadro de origen se desfase al escribir en el recurso de destino; Sin embargo, las dimensiones del cuadro de origen y los desplazamientos deben estar dentro del tamaño del recurso. Si intenta copiar fuera del recurso de destino o especifica un cuadro de origen mayor que el recurso de origen, el comportamiento de CopyTextureRegion no está definido. Si ha creado un dispositivo que admite la capa de depuración, la salida de depuración notifica un error en esta llamada a CopyTextureRegion no válida. Los parámetros no válidos para CopyTextureRegion provocan un comportamiento indefinido y pueden dar lugar a una representación incorrecta, recorte, sin copia o incluso la eliminación del dispositivo de representación.

Si los recursos son búferes, todas las coordenadas están en bytes; si los recursos son texturas, todas las coordenadas están en texturas.

CopyTextureRegion realiza la copia en la GPU (similar a una memcpy por la CPU). Como consecuencia, los recursos de origen y destino:

  • Debe ser subrecursos diferentes (aunque pueden ser del mismo recurso).
  • Debe tener DXGI_FORMATcompatibles (idénticos o del mismo grupo de tipos). Por ejemplo, una textura de DXGI_FORMAT_R32G32B32_FLOAT se puede copiar en una textura DXGI_FORMAT_R32G32B32_UINT, ya que ambos formatos están en el grupo de DXGI_FORMAT_R32G32B32_TYPELESS. CopyTextureRegion puede copiar entre algunos tipos de formato. Para obtener más información, consulta Conversión de formato con Direct3D 10.1.
CopyTextureRegion solo admite la copia; no admite ningún ajuste, tecla de color ni mezcla. CopyTextureRegion puede reinterpretar los datos de recursos entre algunos tipos de formato.

Tenga en cuenta que para un búfer de galería de símbolos de profundidad, los planos de profundidad y galería de símbolos son subrecursos independientes dentro del búfer.

Para copiar un recurso completo, en lugar de simplemente una región de un subrecurso, se recomienda usar CopyResource en su lugar.

Nota Si usa CopyTextureRegion con un búfer de galería de símbolos de profundidad o un recurso de muestreo múltiple, debe copiar todo el rectángulo subrecurso. En esta situación, debe pasar 0 a los parámetros DstX, DstY y DstZ y NULL al parámetro pSrcBox . Además, los recursos de origen y destino, representados por los parámetros pSrcResource y pDstResource , deben tener valores de recuento de muestras idénticos.
 
CopyTextureRegion se puede usar para inicializar recursos que alias la misma memoria del montón. Consulte CreatePlacedResource para obtener más detalles.

Ejemplo

El siguiente fragmento de código copia el cuadro (ubicado en (120 100),(200,220)) de una textura de origen en la región (10,20),(90,140) en una textura de destino. 
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);

Observe que para una textura 2D, la parte delantera y la parte posterior se establecen en 0 y 1 respectivamente.

Ejemplos

El ejemplo HelloTriangle usa ID3D12GraphicsCommandList::CopyTextureRegion de la siguiente manera:

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

Vea Código de ejemplo en la referencia D3D12.

Requisitos

Requisito Value
Plataforma de destino Windows
Encabezado d3d12.h
Library D3d12.lib
Archivo DLL D3d12.dll

Consulte también

CopyBufferRegion

ID3D12GraphicsCommandList