ID3D12Device10::CreatePlacedResource2 method (d3d12.h)

Article
11/03/2022

Creates a resource that is placed in a specific heap. Placed resources are the lightest weight resource objects available, and are the fastest to create and destroy.

Your application can re-use video memory by overlapping multiple Direct3D placed and reserved resources on heap regions. The simple memory re-use model (described in Remarks) exists to clarify which overlapping resource is valid at any given time. To maximize graphics tool support, with the simple model data-inheritance isn't supported; and finer-grained tile and sub-resource invalidation isn't supported. Only full overlapping resource invalidation occurs.

Requires the DirectX 12 Agility SDK 1.7 or later.

Syntax

HRESULT CreatePlacedResource2(
  ID3D12Heap                 *pHeap,
  UINT64                     HeapOffset,
  const D3D12_RESOURCE_DESC1 *pDesc,
  D3D12_BARRIER_LAYOUT       InitialLayout,
  const D3D12_CLEAR_VALUE    *pOptimizedClearValue,
  UINT32                     NumCastableFormats,
  const DXGI_FORMAT          *pCastableFormats,
  REFIID                     riid,
  void                       **ppvResource
);

Parameters

pHeap

Type: [in] ID3D12Heap*

A pointer to the ID3D12Heap interface that represents the heap in which the resource is placed.

HeapOffset

Type: UINT64

The offset, in bytes, to the resource. The HeapOffset must be a multiple of the resource's alignment, and HeapOffset plus the resource size must be smaller than or equal to the heap size. GetResourceAllocationInfo must be used to understand the sizes of texture resources.

pDesc

Type: [in] const D3D12_RESOURCE_DESC*

A pointer to a D3D12_RESOURCE_DESC structure that describes the resource.

InitialLayout

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

pOptimizedClearValue

Type: [in, optional] 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, your application 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.

NumCastableFormats

The number of elements in pCastableFormats.

pCastableFormats

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

riid

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) gets the GUID of the interface to a resource. Although riid 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, then creation fails with E_NOINTERFACE.

ppvResource

Type: [out, optional] void**

A pointer to a memory block that receives a pointer to the resource. 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 and other parameters are valid.

Return value

Type: HRESULT

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

Remarks

See Remarks for ID3D12Device::CreatePlacedResource.

Requirements

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