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

# CreatePlacedResource1 (XBOX Series 主機)

> 建立放置的資源。

建立放置的資源。

## 語法

```cpp theme={null}
HRESULT CreatePlacedResource1(  
         ID3D12Heap* pHeap,  
         UINT64 HeapOffset,  
         const D3D12_RESOURCE_DESC1* pDesc,  
         D3D12_RESOURCE_STATES InitialState,  
         const D3D12_CLEAR_VALUE* pOptimizedClearValue,  
         REFIID riid,  
         void** ppvResource  
)  
```

### 參數

*pHeap*   \_In\_\
類型：ID3D12Heap\*

指向 ID3D12Heap 介面的指標，代表放置資源的堆積。

*HeapOffset*   \
類型：UINT64

資源的位移 (以位元組為單位)。HeapOffset 必須是資源對齊的倍數，且 HeapOffset 加上資源大小必須小於或等於堆積大小。必須使用 GetResourceAllocationInfo 來了解紋理資源的大小。

*pDesc*   \_In\_\
類型：[D3D12\_RESOURCE\_DESC1\*](/zh-TW/reference/graphics/d3d12_xs/structs/d3d12_resource_desc1)

指向描述資源之 D3D12\_RESOURCE\_DESC1 結構的指標。

*InitialState*   \
類型：[D3D12\_RESOURCE\_STATES](/zh-TW/reference/graphics/d3d12_x/enums/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*   \_In\_opt\_\
類型：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*   \_In\_\
類型：REFIID

資源介面的全域唯一識別碼 (GUID)。這是輸入參數。

資源介面的 REFIID 或 GUID 可以使用 \_\_uuidof 巨集取得。例如，\_\_uuidof(ID3D12Resource) 會取得資源介面的 GUID。雖然 riid 最常是 ID3D12Resource 的 GUID，但它可以是任何介面的任何 GUID。如果資源物件不支援此 GUID 的介面，則建立會失敗並傳回 E\_NOINTERFACE。

*ppvResource*   \_COM\_Outptr\_\
類型：void\*\*

指向接收資源指標之記憶體區塊的指標。ppvResource 可以是 NULL，以啟用功能測試。當 ppvResource 為 NULL 時，不會建立任何物件，且當 pResourceDesc 和其他參數有效時會傳回 S\_FALSE。

### 傳回值

類型：HRESULT

如果記憶體不足而無法建立資源，此方法會傳回 E\_OUTOFMEMORY。如需其他可能的傳回值，請參閱 Direct3D 12 傳回碼。

## 備註

CreatePlacedResource 類似於將保留資源完整對應至堆積內的位移；但與堆積相關聯的虛擬位址空間也可以重複使用。

放置的資源在建立和終結時比認可的資源更輕量。這是因為在這些作業期間不會建立或終結任何堆積。此外，放置的資源還提供比建立和終結資源更輕量的記憶體重複使用技術，也就是透過別名和別名屏障進行重複使用。多個放置的資源可以同時在同一個堆積上彼此重疊，但一次只能使用單一重疊的資源。

放置的資源有兩種使用語意：簡單模型和進階模型。除非您發現應用程式需要進階模型，否則建議您選擇簡單模型 (它可在多元的 GPU 生態系統中將圖形工具支援最大化)。

### 簡單模型

在此模型中，您可以將放置的資源視為處於兩種狀態之一：作用中或非作用中。GPU 從非作用中資源讀取或寫入都是無效的。放置的資源是以非作用中狀態建立。

若要在命令清單上使用別名屏障啟用資源，您的應用程式必須在 D3D12\_RESOURCE\_ALIASING\_BARRIER::pResourceAfter 中傳遞資源。啟用期間 pResourceBefore 可以保留為 NULL。所有與已啟用資源共用實體記憶體的資源現在都會變成非作用中，包括重疊的放置資源和保留資源。

別名屏障應該分組並一起提交，以將效率最大化。

啟用之後，具有轉譯目標或深度樣板旗標的資源必須進一步初始化。請參閱下方關於必要資源初始化的注意事項。

#### 必要資源初始化的注意事項

某些資源類型仍需要初始化。具有轉譯目標或深度樣板旗標的資源，必須使用清除作業或一組完整的子資源複製來初始化。如果使用別名屏障來表示兩個別名資源之間的轉換，則初始化必須在別名屏障之後進行。在簡單模型中，每當資源會被啟用時，仍然需要此初始化。

具有轉譯目標或深度樣板旗標的放置資源和保留資源，必須先使用下列其中一項作業初始化，才能支援其他作業。

清除作業；例如 ClearRenderTargetView 或 ClearDepthStencilView。
DiscardResource 作業。
複製作業；例如 CopyBufferRegion、CopyTextureRegion 或 CopyResource。
應用程式應優先使用修改紋素數量最少的最明確作業。請考慮下列範例。

使用深度緩衝區解決像素可見度時，通常需要每個深度紋素從 1.0 或 0 開始。因此，清除作業應該是別名深度緩衝區初始化最有效率的選項。
應用程式可能會使用別名轉譯目標作為色調對應的目的地。由於應用程式在色調對應期間會轉譯每個像素，因此 DiscardResource 應該是最有效率的初始化選項。

### 進階模型

在此模型中，您可以忽略作用中/非作用中狀態抽象。相反地，您必須遵守這些較低層級的規則。

只要對同一實體記憶體的兩個不同 GPU 資源存取位於同一個 ExecuteCommandLists 呼叫內，兩者之間就必須有別名屏障。
對某些類型別名資源的第一個轉譯作業仍必須是初始化，就像簡單模型一樣。
初始化作業必須在整個子資源上進行，或以 64KB 細微度進行。所有資源類型都支援整個子資源初始化。對齊 64KB 位移的 64KB 初始化細微度，支援緩衝區以及具有 64KB\_UNDEFINED\_SWIZZLE 或 64KB\_STANDARD\_SWIZZLE 紋理配置的紋理 (請參閱 D3D12\_TEXTURE\_LAYOUT)。

#### 別名屏障的注意事項

別名屏障可以將 pResourceAfter 和 pResourceBefore 都設為 NULL。ExecuteCommandLists 和別名屏障的記憶體一致性定義相同，因此當對同一實體記憶體的兩個別名存取位於兩個不同的 ExecuteCommandLists 叫用中時，不需要別名屏障。

對於 D3D12 進階使用模型，ExecuteCommandLists 的同步處理定義等同於別名屏障。因此，應用程式可以在重複使用實體記憶體之間插入別名屏障，或確保實體記憶體的兩個別名使用發生在兩個不同的 ExecuteCommandLists 呼叫中。

非作用中的程度會根據資源屬性而有所不同。具有未定義記憶體配置的紋理是最差的情況，因為整個紋理必須以不可部分完成的方式設為非作用中。對於兩個具有已定義配置的重疊資源，非作用中可能只會影響資源中重疊的對齊區域。資料繼承甚至可以明確定義。如需詳細資料，請參閱記憶體別名和資料繼承。

## 需求

**標頭：** d3d12\_xs.h

**程式庫：** d3d12\_xs.lib\
**支援的平台：** XBOX Series 主機

## 另請參閱

[ID3D12Device8](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12Device8/id3d12device8)


## Related topics

- [CreateReservedResource1 (XBOX Series consoles)](/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createreservedresource1_public.md)
- [CreateReservedResource1 (XBOX Series 콘솔)](/ko/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createreservedresource1_public.md)
- [CreateReservedResource1 (XBOX Series 主机)](/zh-CN/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createreservedresource1_public.md)
- [CreateReservedResource1 (consolas XBOX Series)](/es/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createreservedresource1_public.md)
- [CreateReservedResource1 (XBOX Series 本体)](/ja-jp/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createreservedresource1_public.md)