ID3D12GraphicsCommandList::CopyTextureRegion メソッド (d3d12.h)

  • [アーティクル]

この方法では、GPU を使用して 2 つの場所間でテクスチャ データをコピーします。 ソースとターゲットの両方で、バッファー リソースまたはテクスチャ リソース内にあるテクスチャ データを参照できます。

構文

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

パラメーター

[in] pDst

型: const D3D12_TEXTURE_COPY_LOCATION*

変換先の D3D12_TEXTURE_COPY_LOCATIONを指定します。 参照されるサブリソースは、D3D12_RESOURCE_STATE_COPY_DEST状態である必要があります。

DstX

型: UINT

コピー先領域の左上隅の x 座標。

DstY

型: UINT

宛先領域の左上隅の y 座標。 1D サブリソースの場合、これは 0 である必要があります。

DstZ

型: UINT

ターゲット領域の左上隅の z 座標。 1D または 2D サブリソースの場合、これは 0 である必要があります。

[in] pSrc

型: const D3D12_TEXTURE_COPY_LOCATION*

ソース D3D12_TEXTURE_COPY_LOCATIONを指定します。 参照されるサブリソースは、D3D12_RESOURCE_STATE_COPY_SOURCE状態である必要があります。

[in, optional] pSrcBox

型: const D3D12_BOX*

コピーするソース テクスチャのサイズを設定するオプションのD3D12_BOXを指定します。

戻り値

なし

解説

ソース ボックスは、ソース リソースのサイズ内である必要があります。 変換先のオフセット (x、y、z) を使用すると、コピー先リソースに書き込むときにソース ボックスをオフセットできます。ただし、ソース ボックスのディメンションとオフセットは、リソースのサイズ内である必要があります。 コピー先のリソースの外部にコピーしようとしたり、ソース リソースよりも大きいソース ボックスを指定したりすると、 CopyTextureRegion の動作は未定義になります。 デバッグ レイヤーをサポートするデバイスを作成した場合、この無効な CopyTextureRegion 呼び出しでデバッグ出力からエラーが報告されます。 CopyTextureRegion に無効なパラメーターを指定すると、未定義の動作が発生し、レンダリング、クリッピング、コピーなし、さらにはレンダリング デバイスの削除が発生する可能性があります。

リソースがバッファーの場合、すべての座標はバイト単位です。リソースがテクスチャの場合、すべての座標はテクセル内にあります。

CopyTextureRegion は GPU でコピーを実行します (CPU による と同様 memcpy )。 その結果、移行元と移行先のリソースは次のようになります。

  • 異なるサブリソースである必要があります (ただし、同じリソースから取得できます)。
  • (同一または同じ型グループから) DXGI_FORMAT互換性がある必要があります。 たとえば、DXGI_FORMAT_R32G32B32_FLOAT テクスチャは、両方の形式が DXGI_FORMAT_R32G32B32_TYPELESS グループに含まれるため、DXGI_FORMAT_R32G32B32_UINT テクスチャにコピーできます。 CopyTextureRegion は、いくつかの形式の種類間でコピーできます。 詳細については、「 Direct3D 10.1 を使用した変換の書式設定」を参照してください。
CopyTextureRegion では、コピーのみがサポートされます。ストレッチ、カラー キー、またはブレンドはサポートされていません。 CopyTextureRegion では、いくつかの形式の種類の間でリソース データを再解釈できます。

深度ステンシル バッファーの場合、深度とステンシルの平面はバッファー内の 個別のサブリソース であることに注意してください。

サブリソースのリージョンではなく、リソース全体をコピーするには、代わりに CopyResource を使用することをお勧めします。

メモ 深度ステンシル バッファーまたはマルチサンプリング リソースで CopyTextureRegion を使用する場合は、サブリソースの四角形全体をコピーする必要があります。 このような場合は、0 を DstX、 DstY、 DstZ パラメーターに渡し、 NULL をpSrcBox パラメーターに渡す必要があります。 さらに、pSrcResource パラメーターと pDstResource パラメーターで表されるソース リソースと移行先リソースは、同じサンプルカウント値を持つ必要があります。
 
CopyTextureRegion を使用して、同じヒープ メモリに別名を付けるリソースを初期化できます。 詳細については、「 CreatePlacedResource 」を参照してください。

例

次のコード スニペットは、(120,100),(200,220)) のボックスをソース テクスチャからコピー先テクスチャの領域 (10,20),(90,140) にコピーします。 
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);

2D テクスチャの場合、前面と背面はそれぞれ 0 と 1 に設定されていることに注意してください。

例

HelloTriangle サンプルでは、次のように ID3D12GraphicsCommandList::CopyTextureRegion を使用します。

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

「D3D12 リファレンス」のコード例を参照してください。

要件

要件 値
対象プラットフォーム Windows
ヘッダー d3d12.h
Library D3d12.lib
[DLL] D3d12.dll

こちらもご覧ください

CopyBufferRegion

ID3D12GraphicsCommandList