> ## 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.

# WriteToSubresource

> 使用 CPU 將資料複製到子資源，讓 CPU 能夠修改大部分版面配置未定義之紋理的內容。

使用 CPU 將資料複製到子資源，讓 CPU 能夠修改大部分版面配置未定義之紋理的內容。

## 語法

```cpp theme={null}
HRESULT WriteToSubresource(
    UINT DstSubresource,
    const D3D12_BOX  pDstBox,
    const void  pSrcData,
    UINT SrcRowPitch,
    UINT SrcDepthPitch
)
```

### 參數

*DstSubresource*\
類型：UINT

指定子資源的索引。

*pDstBox \[in, optional]*\
類型：const D3D12\_BOX \*

指向方塊的指標，該方塊定義要將資源資料複製到其中的目的地子資源部分。
如果為 NULL，則會將資料寫入目的地子資源，且不含位移。
來源的維度必須符合目的地 (請參閱
[D3D12\_BOX](/zh-TW/reference/graphics/d3d12/structs/d3d12_box_public))。

空方塊會導致無作業。
如果 top 值大於或等於 bottom 值、left 值大於或等於 right 值，
或 front 值大於或等於 back 值，則方塊為空。
當方塊為空時，此方法不會執行任何作業。

*pSrcData \[in]*\
類型：const void \*

指向記憶體中來源資料的指標。

*SrcRowPitch*\
類型：UINT

從來源資料的某一列到下一列的距離。

*SrcDepthPitch*\
類型：UINT

從來源資料的某一個深度切片到下一個深度切片的距離。

### 傳回值

類型：HRESULT

此方法會傳回其中一個 [Direct3D 12 傳回碼](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/d3d12-graphics-reference-returnvalues)。

## 備註

<Note>
  ***注意：*** XBOX Series 主機與 XBOX One 系列目前不支援此功能。
</Note>

資源應先使用
[Map](/zh-TW/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public) 進行對應。紋理必須處於 [D3D12\_RESOURCE\_STATE\_COMMON](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_states) 狀態，透過 **WriteToSubresource** 和 [ReadFromSubresource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_readfromsubresource_public) 進行的 CPU 存取才合法；但緩衝區則不需要。

為了提高效率，請確保方塊內範圍的邊界和對齊在水平方向為 ( 64 / \[每像素位元組數] ) 個像素。
垂直邊界和對齊應為 2 列，但使用每像素 1 位元組的格式時除外，此時建議使用 4 列。
每次呼叫處理單一深度切片可獲得有效率的處理。
建議 (但非必要) 提供 128 位元組對齊的指標和間距。

寫入子 mipmap 層級時，建議使用比上述更大的寬度和高度。
這是因為小型 mipmap 層級實際上可能儲存在較大的記憶體區塊中，且具有不透明的位移量，可能會干擾快取行對齊。

**WriteToSubresource** 和 [ReadFromSubresource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_readfromsubresource_public) 可針對 UMA 介面卡進行近乎零複製的最佳化，但可能會嚴重損害獨立/NUMA 介面卡的效率，因為紋理資料無法常駐在本機視訊記憶體中。一般應用程式應使用適合獨立介面卡的上傳技術，除非應用程式能辨識出介面卡架構為 UMA。如需上傳的詳細資訊，請參閱 [CopyTextureRegion](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_copytextureregion_public)；如需 UMA 的詳細資訊，請參閱 [D3D12\_FEATURE\_DATA\_ARCHITECTURE](/zh-TW/reference/graphics/d3d12/structs/d3d12_feature_data_architecture_public)。

在 UMA 系統上，此常式可透過稱為 [迴圈分塊](https://en.wikipedia.org/wiki/Loop_tiling) 的迴圈最佳化，將記憶體複製的成本降至最低。將上傳分割成可輕鬆放入 CPU 快取的區塊，CPU 與主記憶體之間的有效頻寬就能更接近理論最大值。

## 需求

**標頭:** d3d12\_xs.h 或 d3d12\_x.h\
**程式庫:** d3d12\_xs.lib 或 d3d12\_x.lib\
**支援的平台**: XBOX Series 主機與 XBOX One 系列目前不支援

## 另請參閱

[ID3D12Resource](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs)

[子資源](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/subresources)


## Related topics

- [ReadFromSubresource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_readfromsubresource_public.md)
- [D3D12_BOX](/zh-TW/reference/graphics/d3d12/structs/d3d12_box_public.md)
- [Map](/zh-TW/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public.md)
- [ResolveSubresourceRegion](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist1/methods/id3d12graphicscommandlist1_resolvesubresourceregion_public.md)
- [D3D12_SUBRESOURCE_DATA](/zh-TW/reference/graphics/d3d12/structs/d3d12_subresource_data_public.md)