Skip to content

Latest commit

 

History

History
133 lines (88 loc) · 6.68 KB

nf-d3d12-id3d12device8-createcommittedresource2.md

File metadata and controls

133 lines (88 loc) · 6.68 KB
Raw
UID title description helpviewer_keywords tech.root ms.date targetos req.assembly req.construct-type req.ddi-compliance req.dll req.header req.idl req.include-header req.irql req.kmdf-ver req.lib req.max-support req.namespace req.redist req.target-min-winverclnt req.target-min-winversvr req.target-type req.type-library req.umdf-ver req.unicode-ansi topic_type api_type api_location api_name f1_keywords dev_langs
NF:d3d12.ID3D12Device8.CreateCommittedResource2
ID3D12Device8::CreateCommittedResource2
Creates both a resource and an implicit heap (optionally for a protected session), such that the heap is big enough to contain the entire resource, and the resource is mapped to the heap.
ID3D12Device8 interface
CreateCommittedResource2 method
ID3D12Device8.CreateCommittedResource2
ID3D12Device8::CreateCommittedResource2
CreateCommittedResource2
CreateCommittedResource2 method
CreateCommittedResource2 method
ID3D12Device8 interface
direct3d12.id3d12device7_createcommittedresource2
d3d12/ID3D12Device8::CreateCommittedResource2
direct3d12
09/16/2020
Windows
function
d3d12.dll
d3d12.h
d3d12.lib
Windows 10 Build 20348
Windows 10 Build 20348
apiref
COM
d3d12.lib
d3d12.dll
ID3D12Device8::CreateCommittedResource2
d3d12/ID3D12Device8::CreateCommittedResource2
c++

-description

Creates both a resource and an implicit heap (optionally for a protected session), such that the heap is big enough to contain the entire resource, and the resource is mapped to the heap. Also see ID3D12Device::CreateCommittedResource for a code example.

-parameters

-param pHeapProperties

Type: _In_ const D3D12_HEAP_PROPERTIES*

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

-param HeapFlags

Type: D3D12_HEAP_FLAGS

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

-param pDesc

Type: const D3D12_RESOURCE_DESC1*

A pointer to a D3D12_RESOURCE_DESC1 structure that describes the resource, including a mip region.

-param InitialResourceState

Type: D3D12_RESOURCE_STATES

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

When you create a resource together with a D3D12_HEAP_TYPE_UPLOAD heap, you must set InitialResourceState to D3D12_RESOURCE_STATE_GENERIC_READ.

When you create a resource together with a D3D12_HEAP_TYPE_READBACK heap, you must set InitialResourceState to D3D12_RESOURCE_STATE_COPY_DEST.

-param pOptimizedClearValue

Type: const D3D12_CLEAR_VALUE*

Specifies a D3D12_CLEAR_VALUE structure 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, you should choose the value with which the clear operation will most commonly be called. You can call the clear operation with other values, but those operations won't be as efficient as when the value matches the one passed in to resource creation.

When you use D3D12_RESOURCE_DIMENSION_BUFFER, you must set pOptimizedClearValue to nullptr.

-param pProtectedSession

Type: ID3D12ProtectedResourceSession*

An optional pointer to an object that represents a session for content protection. If provided, this session indicates that the resource should be protected. You can obtain an ID3D12ProtectedResourceSession by calling ID3D12Device4::CreateProtectedResourceSession.

-param riidResource

Type: REFIID

A reference to the globally unique identifier (GUID) of the resource interface to return in ppvResource.

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

-param ppvResource

Type: void**

An optional pointer to a memory block that receives the requested interface pointer to the created resource object.

ppvResource can be nullptr, to enable capability testing. When ppvResource is nullptr, no object is created, and S_FALSE is returned when pDesc is valid.

-returns

Type: HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Return value Description
E_OUTOFMEMORY There is insufficient memory to create the resource.

See Direct3D 12 return codes for other possible return values.

-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 can't be obtained by the application. Before releasing the final reference on the resource, your application must ensure that the GPU will no longer read nor write to this resource.

The implicit heap is made resident for GPU access before the method returns control to your application. Also see Residency.

The resource GPU VA mapping can't be changed. See ID3D12CommandQueue::UpdateTileMappings and Volume tiled resources.

This method may be called by multiple threads concurrently.

-see-also