Edit

Share via

ID3D12Device10::CreateCommittedResource3 method (d3d12.h)

  • Article

Creates a committed resource with an initial layout rather than an initial state.

Requires the DirectX 12 Agility SDK 1.7 or later.

Syntax

HRESULT CreateCommittedResource3(
  const D3D12_HEAP_PROPERTIES    *pHeapProperties,
  D3D12_HEAP_FLAGS               HeapFlags,
  const D3D12_RESOURCE_DESC1     *pDesc,
  D3D12_BARRIER_LAYOUT           InitialLayout,
  const D3D12_CLEAR_VALUE        *pOptimizedClearValue,
  ID3D12ProtectedResourceSession *pProtectedSession,
  UINT32                         NumCastableFormats,
  const DXGI_FORMAT              *pCastableFormats,
  REFIID                         riidResource,
  void                           **ppvResource
);

Parameters

pHeapProperties

Type: _In_ 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

Type: const D3D12_RESOURCE_DESC1*

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

InitialLayout

The initial layout of the texture resource; D3D12_BARRIER_LAYOUT::D3D12_BARRIER_LAYOUT_UNDEFINED for buffers.

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.

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.

NumCastableFormats

The number of elements in pCastableFormats.

pCastableFormats

A contiguous array of DXGI_FORMAT structures that this resource can be cast to.

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.

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.

Return value

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.

Requirements

Requirement Value
Target Platform Windows
Header d3d12.h
Library D3d12.lib
DLL D3d12.dll

See also

ID3D12Device10