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

# CreateCommittedResource

> 同時建立資源和隱含堆積，使堆積大到足以包含整個資源，並將資源對應至該堆積。

同時建立資源和隱含堆積，使堆積大到足以包含整個資源，並將資源對應至該堆積。

## 語法

```cpp theme={null}
HRESULT CreateCommittedResource(
    const D3D12_HEAP_PROPERTIES  pHeapProperties,
    D3D12_HEAP_FLAGS HeapFlags,
    const D3D12_RESOURCE_DESC* pDesc,
    D3D12_RESOURCE_STATES InitialResourceState,
    const D3D12_CLEAR_VALUE  pOptimizedClearValue,
    const IID & riidResource,
    void  ppvResource
)
```

### 參數

*pHeapProperties \[in]*<br />類型：const D3D12\_HEAP\_PROPERTIES \*

指向 **D3D12\_HEAP\_PROPERTIES** 結構的指標，提供資源之堆積的屬性。

*HeapFlags \[in]*<br />類型：D3D12\_HEAP\_FLAGS

堆積選項，以 **D3D12\_HEAP\_FLAGS** 列舉常數的位元 OR 組合表示。

*pDesc \[in]*<br />類型：**const [D3D12\_RESOURCE\_DESC](/zh-TW/reference/graphics/d3d12/structs/d3d12_resource_desc_public)\***

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

*InitialResourceState \[in]*<br />類型：[**D3D12\_RESOURCE\_STATES**](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_states)

資源的初始狀態，以 **D3D12\_RESOURCE\_STATES** 列舉常數的位元 OR 組合表示。

當您搭配 [D3D12\_HEAP\_TYPE\_UPLOAD](/zh-TW/reference/graphics/d3d12/enums/d3d12_heap_type_public) 堆積建立資源時，必須將 *InitialResourceState* 設為 [D3D12\_RESOURCE\_STATE\_GENERIC\_READ](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_states)。

當您搭配 [D3D12\_HEAP\_TYPE\_READBACK](/zh-TW/reference/graphics/d3d12/enums/d3d12_heap_type_public) 堆積建立資源時，必須將 *InitialResourceState* 設為 [D3D12\_RESOURCE\_STATE\_COPY\_DEST](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_states)。

*pOptimizedClearValue \[in, optional]*<br />類型：const D3D12\_CLEAR\_VALUE \*

指定描述清除色彩預設值的 **D3D12\_CLEAR\_VALUE** 結構。

*pOptimizedClearValue* 指定可讓清除作業達到最佳效能的值。當建立的資源是具有 [D3D12\_RESOURCE\_FLAG\_ALLOW\_RENDER\_TARGET](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_flags) 或 **D3D12\_RESOURCE\_FLAG\_ALLOW\_DEPTH\_STENCIL** 旗標的紋理時，您應該選擇最常用來呼叫清除作業的值。您可以使用其他值呼叫清除作業，但這些作業的效率會不如值與建立資源時傳入的值相符時那麼高。

當您使用 [D3D12\_RESOURCE\_DIMENSION\_BUFFER](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_dimension) 時，必須將 *pOptimizedClearValue* 設為 `nullptr`。

*riidResource \[in]*<br />類型：const IID &

要在 *ppvResource* 中傳回之資源介面的全域唯一識別碼 (**GUID**) 參考。

雖然 *riidResource* 最常是 [ID3D12Resource](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs) 的 **GUID**，但它可以是任何介面的 **GUID**。如果資源物件不支援此 **GUID** 的介面，建立就會失敗並傳回 **E\_NOINTERFACE**。

*ppvResource \[out, optional]*<br />類型：void \*\*

指向記憶體區塊的選擇性指標，該區塊會接收所要求之已建立資源物件的介面指標。

*ppvResource* 可以是 `nullptr`，以啟用功能測試。當 *ppvResource* 為 `nullptr` 時，不會建立任何物件，且當 *pDesc* 有效時會傳回 **S\_FALSE**。

### 傳回值

類型：HRESULT

如果函式成功，會傳回 **S\_OK**。否則會傳回 [**HRESULT**](https://learn.microsoft.com/en-us/windows/desktop/com/structure-of-com-error-codes) [錯誤碼](https://learn.microsoft.com/en-us/windows/win32/com/com-error-codes-10)。

| 傳回值 | 描述 |
| - | - |
| E\_OUTOFMEMORY | 記憶體不足，無法建立資源。 |

如需其他可能的傳回值，請參閱 [Direct3D 12 傳回碼](https://learn.microsoft.com/en-us/windows/win32/direct3d12/d3d12-graphics-reference-returnvalues)。

## 備註

此方法會同時建立資源和堆積，使堆積大到足以包含整個資源，並將資源對應至該堆積。建立的堆積稱為隱含堆積，因為應用程式無法取得該堆積物件。在釋放資源的最後一個參考之前，您的應用程式必須確保 GPU 不會再讀取或寫入此資源。

在方法將控制權交還給您的應用程式之前，隱含堆積會設為常駐，以供 GPU 存取。另請參閱[常駐](https://learn.microsoft.com/en-us/windows/win32/direct3d12/residency)。

資源的 GPU VA 對應無法變更。請參閱 [ID3D12CommandQueue::UpdateTileMappings](/zh-TW/reference/graphics/d3d12/interfaces/id3d12commandqueue/methods/id3d12commandqueue_updatetilemappings_public) 和[磚狀體積資源](https://learn.microsoft.com/en-us/windows/win32/direct3d12/volume-tiled-resources)。

此方法可由多個執行緒同時呼叫。

## 範例

[D3D12Bundles](https://learn.microsoft.com/en-us/windows/win32/direct3d12/working-samples) 範例使用 **ID3D12Device::CreateCommittedResource** 的方式如下：

建立頂點緩衝區。

```cpp theme={null}
auto heapProperties = CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_DEFAULT);
auto resourceDesc = CD3DX12_RESOURCE_DESC::Buffer(SampleAssets::VertexDataSize);
ThrowIfFailed(m_device->CreateCommittedResource(
&heapProperties,
D3D12_HEAP_FLAG_NONE,
&resourceDesc,
D3D12_RESOURCE_STATE_COPY_DEST,
nullptr,
IID_PPV_ARGS(&m_vertexBuffer)));
```

請參閱 [Direct3D 12 參考中的範例程式碼](https://learn.microsoft.com/en-us/windows/win32/direct3d12/notes-on-example-code)。

## 需求

**標頭：** d3d12\_xs.h 或 d3d12\_x.h<br />**程式庫：** d3d12\_xs.lib 或 d3d12\_x.lib<br />**支援的平台**：XBOX Series 主機與 XBOX One 系列

## 另請參閱

[CreatePlacedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createplacedresource_public)

[CreateReservedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createreservedresource_public)

[D3D12\_HEAP\_FLAGS](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_heap_flags)

[ID3D12Device](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/id3d12device)


## Related topics

- [CreateCommittedResource1 (XBOX Series 主機)](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createcommittedresource1_public.md)
- [CreateReservedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createreservedresource_public.md)
- [CreatePlacedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createplacedresource_public.md)
- [CreateReservedResource2 (XBOX Series 主機)](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device10/methods/id3d12device10_createreservedresource2_public.md)
- [CreatePlacedResource2 (XBOX Series 主機)](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device10/methods/id3d12device10_createplacedresource2_public.md)