> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GetCopyableFootprints

> 获取可以复制的资源布局。帮助应用在子分配空间时填写 D3D12_PLACED_SUBRESOURCE_FOOTPRINT 和 D3D12_SUBRESOURCE_FOOTPRINT。

获取可以复制的资源布局。
帮助应用在上传堆中子分配空间时填写
[D3D12\_PLACED\_SUBRESOURCE\_FOOTPRINT](/reference/graphics/d3d12/structs/d3d12_placed_subresource_footprint_public) 和
[D3D12\_SUBRESOURCE\_FOOTPRINT](/reference/graphics/d3d12/structs/d3d12_subresource_footprint_public)。

## 语法

```cpp theme={null}
void GetCopyableFootprints(
    const D3D12_RESOURCE_DESC  pResourceDesc,
    UINT FirstSubresource,
    UINT NumSubresources,
    UINT64 BaseOffset,
    D3D12_PLACED_SUBRESOURCE_FOOTPRINT  pLayouts,
    UINT  pNumRows,
    UINT64  pRowSizeInBytes,
    UINT64  pTotalBytes
)
```

### 参数

*pResourceDesc \[in]*\
类型：const D3D12\_RESOURCE\_DESC \*

资源的描述，作为指向 [D3D12\_RESOURCE\_DESC](/reference/graphics/d3d12/structs/d3d12_resource_desc_public) 结构体的指针。

*FirstSubresource \[in]*\
类型：UINT

资源中第一个子资源的索引。
有效值范围为 0 到 D3D12\_REQ\_SUBRESOURCES。

*NumSubresources \[in]*\
类型：UINT

资源中子资源的数量。有效值范围为 0 到 (D3D12\_REQ\_SUBRESOURCES - <i>FirstSubresource</i>)。

*BaseOffset*\
类型：UINT64

资源的偏移量（以字节为单位）。

*pLayouts \[out, optional]*\
类型：D3D12\_PLACED\_SUBRESOURCE\_FOOTPRINT \*

指向 [D3D12\_PLACED\_SUBRESOURCE\_FOOTPRINT](/reference/graphics/d3d12/structs/d3d12_placed_subresource_footprint_public) 结构体数组（长度为 <i>NumSubresources</i>）的指针，将使用每个子资源的描述和放置进行填充。

*pNumRows \[out, optional]*\
类型：UINT \*

指向整数变量数组（长度为 <i>NumSubresources</i>）的指针，将使用每个子资源的行数进行填充。

*pRowSizeInBytes \[out, optional]*\
类型：UINT64 \*

指向整数变量数组（长度为 <i>NumSubresources</i>）的指针，每个条目将使用每个子资源的一行的未填充大小（以字节为单位）进行填充。

例如，如果 Texture2D 资源的宽度为 32，每个像素的字节数为 4，

则 <i>pRowSizeInBytes</i> 返回 128。

<i>pRowSizeInBytes</i> 不应与 **行间距** 混淆，因为检查 <i>pLayouts</i> 并从中获取行间距将得到 256，因为它与 D3D12\_TEXTURE\_DATA\_PITCH\_ALIGNMENT 对齐。

*pTotalBytes \[out, optional]*\
类型：UINT64 \*

指向整数变量的指针，将使用总大小（以字节为单位）进行填充。

### 返回值

类型：void

无。

## 备注

此例程协助应用程序在上传堆中子分配空间时填写
[D3D12\_PLACED\_SUBRESOURCE\_FOOTPRINT](/reference/graphics/d3d12/structs/d3d12_placed_subresource_footprint_public) 和
[D3D12\_SUBRESOURCE\_FOOTPRINT](/reference/graphics/d3d12/structs/d3d12_subresource_footprint_public) 结构体。
生成的结构体与 GPU 适配器无关，这意味着值不会因 GPU 适配器不同而变化。
**GetCopyableFootprints** 使用有关资源格式、纹理布局和对齐要求的指定详细信息（来自 [D3D12\_RESOURCE\_DESC](/reference/graphics/d3d12/structs/d3d12_resource_desc_public) 结构体）来填写子资源结构体。
应用程序可以访问所有这些详细信息，因此此方法或其变体可以作为应用程序的一部分编写。

#### 示例

[D3D12Multithreading](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/working-samples) 示例按以下方式使用 **ID3D12Device::GetCopyableFootprints**：

```cpp theme={null}
// Returns required size of a buffer to be used for data upload
inline UINT64 GetRequiredIntermediateSize(
_In_ ID3D12Resource* pDestinationResource,
_In_range_(0,D3D12_REQ_SUBRESOURCES) UINT FirstSubresource,
_In_range_(0,D3D12_REQ_SUBRESOURCES-FirstSubresource) UINT NumSubresources)
{
D3D12_RESOURCE_DESC Desc = pDestinationResource->GetDesc();
UINT64 RequiredSize = 0;

ID3D12Device* pDevice;
pDestinationResource->GetDevice(__uuidof(*pDevice), reinterpret_cast<void**>(&pDevice));
pDevice->GetCopyableFootprints(&Desc, FirstSubresource, NumSubresources, 0, nullptr, nullptr, nullptr, &RequiredSize);
pDevice->Release();

return RequiredSize;
}

```

请参阅 [D3D12 参考中的示例代码](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/notes-on-example-code)。

<div class="code" />

## 要求

**头文件：** d3d12\_xs.h 或 d3d12\_x.h\
**库：** d3d12\_xs.lib 或 d3d12\_x.lib\
**支持的平台**：XBOX Series 主机和 XBOX One 系列

## 另请参阅

[CD3DX12\_RESOURCE\_DESC](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/cd3dx12-resource-desc)

[CD3DX12\_SUBRESOURCE\_FOOTPRINT](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/cd3dx12-subresource-footprint)

[ID3D12Device](/reference/graphics/d3d12_x/interfaces/id3d12device/id3d12device)


## Related topics

- [D3D12_PLACED_SUBRESOURCE_FOOTPRINT](/zh-CN/reference/graphics/d3d12/structs/d3d12_placed_subresource_footprint_public.md)
- [D3D12_SUBRESOURCE_FOOTPRINT](/zh-CN/reference/graphics/d3d12/structs/d3d12_subresource_footprint_public.md)
- [D3D12_TEXTURE_COPY_TYPE](/zh-CN/reference/graphics/d3d12/enums/d3d12_texture_copy_type_public.md)
- [D3D12_TEXTURE_COPY_LOCATION](/zh-CN/reference/graphics/d3d12/structs/d3d12_texture_copy_location_public.md)
- [针对 PC 的 MSIXVC2 打包入门](/zh-CN/build/core-features/common/packaging/overviews/packaging-getting-started-for-PC-msixvc2.md)