ID3D12Device8::CreatePlacedResource1 method (d3d12.h)
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.
Syntax
HRESULT CreatePlacedResource1(
ID3D12Heap *pHeap,
UINT64 HeapOffset,
const D3D12_RESOURCE_DESC1 *pDesc,
D3D12_RESOURCE_STATES InitialState,
const D3D12_CLEAR_VALUE *pOptimizedClearValue,
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_DESC1*
A pointer to a D3D12_RESOURCE_DESC1 structure that describes the resource, including a mip region.
InitialState
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, InitialState must be D3D12_RESOURCE_STATE_GENERIC_READ. When a resource is created together with a D3D12_HEAP_TYPE_READBACK heap, InitialState must be D3D12_RESOURCE_STATE_COPY_DEST.
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.
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 ID3D12Device::CreatePlacedResource.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 10 Build 20348 |
| Minimum supported server | Windows 10 Build 20348 |
| Header | d3d12.h |
| Library | d3d12.lib |
| DLL | d3d12.dll |