ID3D12Device::CreateCommittedResource method

Creates both a resource and an implicit heap, such that the heap is big enough to contain the entire resource and the resource is mapped to the heap.

Syntax


HRESULT CreateCommittedResource(
  [in]            const D3D12_HEAP_PROPERTIES *pHeapProperties,
                        D3D12_HEAP_FLAGS      HeapFlags,
  [in]            const D3D12_RESOURCE_DESC   *pDesc,
                        D3D12_RESOURCE_STATES InitialResourceState,
  [in, optional]  const D3D12_CLEAR_VALUE     *pOptimizedClearValue,
                        REFIID                riidResource,
  [out, optional]       void                  **ppvResource
);

Parameters

pHeapProperties [in]

Type: const D3D12_HEAP_PROPERTIES*

A pointer to a D3D12_HEAP_PROPERTIES structure that provides properties for the resource's heap.

HeapFlags

Type: D3D12_HEAP_FLAGS

Heap options, as a bitwise-OR'd combination of D3D12_HEAP_FLAGS enumeration constants.

pDesc [in]

Type: const D3D12_RESOURCE_DESC*

A pointer to a D3D12_RESOURCE_DESC structure that describes the resource.

InitialResourceState

Type: D3D12_RESOURCE_STATES

The initial state of the resource, as a bitwise-OR'd combination of D3D12_RESOURCE_STATES enumeration constants.

When a resource is created together with a D3D12_HEAP_TYPE_UPLOAD heap, InitialResourceState must be D3D12_RESOURCE_STATE_GENERIC_READ. When a resource is created together with a D3D12_HEAP_TYPE_READBACK heap, InitialResourceState must be D3D12_RESOURCE_STATE_COPY_DEST.

pOptimizedClearValue [in, optional]

Type: const D3D12_CLEAR_VALUE*

Specifies a D3D12_CLEAR_VALUE that describes the default value for a clear color.

pOptimizedClearValue specifies a value for which clear operations are most optimal. When the created resource is a texture with either the D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET or D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL flags, applications should choose the value that the clear operation will most commonly be called with. Clear operations can be called with other values, but those operations will not be as efficient as when the value matches the one passed into resource creation. pOptimizedClearValue must be NULL when used with D3D12_RESOURCE_DIMENSION_BUFFER.

riidResource

Type: REFIID

The globally unique identifier (GUID) for the resource interface. This is an input parameter. The REFIID, or GUID, of the interface to the resource can be obtained by using the __uuidof() macro. For example, __uuidof(ID3D12Resource) will get the GUID of the interface to a resource.

While riidResource is, most commonly, the GUID for ID3D12Resource, it may be any GUID for any interface. If the resource object doesn't support the interface for this GUID, creation will fail with E_NOINTERFACE.

ppvResource [out, optional]

Type: void**

A pointer to memory that receives the requested interface pointer to the created resource object. ppvResource can be NULL, to enable capability testing. When ppvResource is NULL, no object will be created and S_FALSE will be returned when pResourceDesc is valid.

Return value

Type: HRESULT

This method returns E_OUTOFMEMORY if there is insufficient memory to create the resource. For other possible return values, see Direct3D 12 Return Codes.

Remarks

This method creates both a resource and a heap, such that the heap is big enough to contain the entire resource and the resource is mapped to the heap. The created heap is known as an implicit heap, because the heap object cannot be obtained by the application. The application must ensure the GPU will no longer read or write to this resource before releasing the final reference on the resource.

The implicit heap is made resident for GPU access before the method returns to the application. See Residency.

The resource GPU VA mapping cannot be changed. See ID3D12CommandQueue::UpdateTileMappings and Volume Tiled Resources.

This method may be called by multiple threads concurrently.

Examples

The D3D12Bundles sample uses ID3D12Device::CreateCommittedResource as follows:

Create a vertex buffer.


ThrowIfFailed(m_device->CreateCommittedResource(
    &CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_DEFAULT),
    D3D12_HEAP_FLAG_NONE,
    &CD3DX12_RESOURCE_DESC::Buffer(SampleAssets::VertexDataSize),
    D3D12_RESOURCE_STATE_COPY_DEST,
    nullptr,
    IID_PPV_ARGS(&m_vertexBuffer)));


See Example Code in the D3D12 Reference.

Requirements

Header

D3D12.h

Library

D3D12.lib

DLL

D3D12.dll

See also

CreatePlacedResource
CreateReservedResource
D3D12_HEAP_FLAGS
ID3D12Device

 

 

Show: