> ## 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](/reference/graphics/d3d12/structs/d3d12_resource_desc_public)\***

指向 **D3D12\_RESOURCE\_DESC** 结构体的指针，该结构体描述资源。

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

资源的初始状态，为 **D3D12\_RESOURCE\_STATES** 枚举常量的按位 OR 组合。

当将资源与 [D3D12\_HEAP\_TYPE\_UPLOAD](/reference/graphics/d3d12/enums/d3d12_heap_type_public) 堆一起创建时，必须将 *InitialResourceState* 设置为 [D3D12\_RESOURCE\_STATE\_GENERIC\_READ](/reference/graphics/d3d12_x/enums/d3d12_resource_states)。

当将资源与 [D3D12\_HEAP\_TYPE\_READBACK](/reference/graphics/d3d12/enums/d3d12_heap_type_public) 堆一起创建时，必须将 *InitialResourceState* 设置为 [D3D12\_RESOURCE\_STATE\_COPY\_DEST](/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](/reference/graphics/d3d12_x/enums/d3d12_resource_flags) 或 **D3D12\_RESOURCE\_FLAG\_ALLOW\_DEPTH\_STENCIL** 标志的纹理时，应选择最常用于清除操作的值。您可以使用其他值调用清除操作，但这些操作不会像值与传递给资源创建的值相匹配时那么高效。

当使用 [D3D12\_RESOURCE\_DIMENSION\_BUFFER](/reference/graphics/d3d12_x/enums/d3d12_resource_dimension) 时，必须将 *pOptimizedClearValue* 设置为 `nullptr`。

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

要在 *ppvResource* 中返回的资源接口的全局唯一标识符 (**GUID**) 的引用。

虽然 *riidResource* 最常是 [ID3D12Resource](/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](/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](/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createplacedresource_public)

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

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

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


## Related topics

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