> ## 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.
# CreatePlacedResource
> ID3D12Device::CreatePlacedResource 會在 XBOX Direct3D 12 上建立放置於特定堆積中的輕量型資源，這是建立速度最快的資源類型。
建立放置在特定堆積中的資源。放置資源是可用的最輕量資源物件，建立和終結的速度也最快。
您的應用程式可以在堆積區域上重疊多個 Direct3D 放置資源和保留資源，藉此重複使用視訊記憶體。簡單記憶體重複使用模型 (如[備註](#remarks)中所述) 的存在，是為了釐清在任何指定時間哪個重疊資源有效。為了最大化圖形工具支援，簡單模型不支援資料繼承，也不支援更精細的圖格和子資源失效。只會發生完整的重疊資源失效。
## 語法
```cpp theme={null}
HRESULT CreatePlacedResource(
ID3D12Heap pHeap,
UINT64 HeapOffset,
const D3D12_RESOURCE_DESC pDesc,
D3D12_RESOURCE_STATES InitialState,
const D3D12_CLEAR_VALUE pOptimizedClearValue,
const IID & riid,
void ppvResource
)
```
### 參數
*pHeap*
類型：ID3D12Heap \*
指向 **ID3D12Heap** 介面的指標，該介面代表放置資源的堆積。
*HeapOffset*
類型：UINT64
資源的位移 (以位元組為單位)。*HeapOffset* 必須是資源對齊的倍數，且 *HeapOffset* 加上資源大小必須小於或等於堆積大小。必須使用 [**GetResourceAllocationInfo**](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_getresourceallocationinfo_public) 來了解紋理資源的大小。
*pDesc*
類型：const D3D12\_RESOURCE\_DESC \*
指向描述資源之 **D3D12\_RESOURCE\_DESC** 結構的指標。
*InitialState*
類型：D3D12\_RESOURCE\_STATES
資源的初始狀態，以 **D3D12\_RESOURCE\_STATES** 列舉常數的位元 OR 組合表示。
當資源與 **D3D12\_HEAP\_TYPE\_UPLOAD** 堆積一起建立時，*InitialState* 必須是 **D3D12\_RESOURCE\_STATE\_GENERIC\_READ**。當資源與 **D3D12\_HEAP\_TYPE\_READBACK** 堆積一起建立時，*InitialState* 必須是 **D3D12\_RESOURCE\_STATE\_COPY\_DEST**。
*pOptimizedClearValue*
類型：const D3D12\_CLEAR\_VALUE \*
指定描述清除色彩預設值的 **D3D12\_CLEAR\_VALUE**。
*pOptimizedClearValue* 指定清除作業最佳化的值。當建立的資源是具有 **D3D12\_RESOURCE\_FLAG\_ALLOW\_RENDER\_TARGET** 或 **D3D12\_RESOURCE\_FLAG\_ALLOW\_DEPTH\_STENCIL** 旗標的紋理時，您的應用程式應該選擇最常用來呼叫清除作業的值。
清除作業可以使用其他值呼叫，但這些作業的效率不如值符合傳入資源建立之值的情況。
搭配 **D3D12\_RESOURCE\_DIMENSION\_BUFFER** 使用時，*pOptimizedClearValue* 必須為 NULL。
*riid*
類型：const IID &
資源介面的全域唯一識別碼 (**GUID**)。這是輸入參數。
您可以使用 `__uuidof` 巨集取得資源介面的 **REFIID** 或 **GUID**。例如，`__uuidof(ID3D12Resource)` 會取得資源介面的 **GUID**。雖然 **riid** 最常是 [**ID3D12Resource**](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs) 的 GUID，但它可以是任何介面的任何 **GUID**。如果資源物件不支援此 **GUID** 的介面，建立作業會失敗並傳回 **E\_NOINTERFACE**。
*ppvResource*
類型：void \*\*
指向接收資源指標之記憶體區塊的指標。*ppvResource* 可以是 NULL，以啟用功能測試。當 *ppvResource* 為 NULL 時，不會建立任何物件，且當 *pResourceDesc* 和其他參數有效時，會傳回 S\_FALSE。
### 傳回值
類型：HRESULT
如果記憶體不足而無法建立資源，此方法會傳回 **E\_OUTOFMEMORY**。如需其他可能的傳回值，請參閱 [Direct3D 12 傳回碼](https://learn.microsoft.com/en-us/windows/win32/direct3d12/d3d12-graphics-reference-returnvalues)。
## 備註
**CreatePlacedResource** 類似於將保留資源完整對應至堆積內的位移；但與堆積相關聯的虛擬位址空間也可以重複使用。
放置資源的建立和終結比認可資源更輕量。這是因為在這些作業期間不會建立或終結任何堆積。此外，放置資源可實現比資源建立和終結更輕量的記憶體重複使用技術，也就是透過別名和別名屏障進行重複使用。多個放置資源可以同時在同一個堆積上彼此重疊，但一次只能使用單一重疊資源。
放置資源有兩種使用語意：簡單模型和進階模型。我們建議您選擇簡單模型 (它能在多樣化的 GPU 生態系統中最大化圖形工具支援)，除非您發現您的應用程式需要進階模型。
### 簡單模型
在此模型中，您可以將放置資源視為處於兩種狀態之一：作用中或非作用中。GPU 從非作用中資源讀取或寫入都是無效的。放置資源會在非作用中狀態下建立。
若要在命令清單上使用別名屏障啟用資源，您的應用程式必須在 [**D3D12\_RESOURCE\_ALIASING\_BARRIER::pResourceAfter**](/zh-TW/reference/graphics/d3d12/structs/d3d12_resource_aliasing_barrier_public) 中傳遞資源。啟用期間 **pResourceBefore** 可以保留為 NULL。所有與已啟用資源共用實體記憶體的資源現在都會變成非作用中，包括重疊的放置資源和保留資源。
別名屏障應該分組並一起提交，以最大化效率。
啟用之後，具有轉譯目標或深度樣板旗標的資源必須進一步初始化。請參閱下方關於必要資源初始化的注意事項。
#### 必要資源初始化的注意事項
某些資源類型仍然需要初始化。具有轉譯目標或深度樣板旗標的資源必須使用清除作業或一組完整子資源複製來初始化。如果使用別名屏障來表示兩個別名資源之間的轉換，則初始化必須在別名屏障之後進行。每當資源在簡單模型中會被啟用時，仍然需要此初始化。
具有轉譯目標或深度樣板旗標的放置資源和保留資源，必須先使用下列其中一項作業初始化，才能支援其他作業。
* *Clear* 作業；例如 [ClearRenderTargetView](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12GraphicsCommandList/methods/id3d12graphicscommandlist_clearrendertargetview_xs) 或 [ClearDepthStencilView](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_cleardepthstencilview_public)。
* [DiscardResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_discardresource_public) 作業。
* *Copy* 作業；例如 [CopyBufferRegion](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_copybufferregion_public)、[CopyTextureRegion](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_copytextureregion_public) 或 [CopyResource](https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12graphicscommandlist-copyresource)。
應用程式應優先使用最明確、修改最少紋素的作業。請考慮下列範例。
* 使用深度緩衝區解決像素可見度時，通常需要每個深度紋素從 1.0 或 0 開始。因此，*Clear* 作業應該是別名深度緩衝區初始化最有效率的選項。
* 應用程式可能會使用別名轉譯目標作為色調對應的目的地。由於應用程式在色調對應期間會轉譯每個像素，因此 [DiscardResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_discardresource_public) 應該是最有效率的初始化選項。
### 進階模型
在此模型中，您可以忽略作用中/非作用中狀態的抽象概念。相反地，您必須遵守這些較低層級的規則。
* 只要對同一實體記憶體的兩次不同 GPU 資源存取位於同一個 [ExecuteCommandLists](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists) 呼叫內，這兩次存取之間就必須有別名屏障。
* 對某些類型別名資源的第一次轉譯作業仍然必須是初始化，就像簡單模型一樣。
初始化作業必須在整個子資源上進行，或以 64KB 細微度進行。所有資源類型都支援整個子資源的初始化。對於緩衝區，以及具有 64KB\_UNDEFINED\_SWIZZLE 或 64KB\_STANDARD\_SWIZZLE 紋理配置 (請參閱 [D3D12\_TEXTURE\_LAYOUT](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_texture_layout)) 的紋理，支援在 64KB 位移處對齊的 64KB 初始化細微度。
### 別名屏障的注意事項
別名屏障可以將 *pResourceAfter* 和 *pResourceBefore* 都設為 NULL。[**ExecuteCommandLists**](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists) 與別名屏障的記憶體一致性定義相同，因此當對同一實體記憶體的兩次別名存取位於兩個不同的 **ExecuteCommandLists** 叫用中時，就不需要別名屏障。
對於 D3D12 進階使用模型，[**ExecuteCommandLists**](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists) 的同步處理定義等同於別名屏障。因此，應用程式可以在重複使用實體記憶體之間插入別名屏障，或確保實體記憶體的兩次別名使用發生在兩個不同的 **ExecuteCommandLists** 呼叫中。
失效的程度會根據資源屬性而有所不同。具有未定義記憶體配置的紋理是最糟的情況，因為整個紋理必須以不可分割的方式失效。對於兩個具有已定義配置的重疊資源，失效可能只會影響資源的重疊對齊區域。資料繼承甚至可以明確定義。如需詳細資訊，請參閱[記憶體別名和資料繼承](https://learn.microsoft.com/en-us/windows/win32/direct3d12/memory-aliasing-and-data-inheritance)。
## 需求
**標頭：** d3d12\_xs.h 或 d3d12\_x.h
**程式庫：** d3d12\_xs.lib 或 d3d12\_x.lib
**支援的平台：** XBOX Series 主機和 XBOX One 系列主機
## 另請參閱
[CreateCommittedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createcommittedresource_public)
[CreateReservedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createreservedresource_public)
[ID3D12Device](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/id3d12device)
[共用堆積](https://learn.microsoft.com/en-us/windows/win32/direct3d12/shared-heaps)
## Related topics
- [CreatePlacedResource2 (XBOX Series 主機)](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device10/methods/id3d12device10_createplacedresource2_public.md)
- [CreateReservedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createreservedresource_public.md)
- [CreateCommittedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createcommittedresource_public.md)
- [CreateReservedResource2 (XBOX Series 主機)](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device10/methods/id3d12device10_createreservedresource2_public.md)
- [CreateReservedResource1 (XBOX Series 主機)](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createreservedresource1_public.md)