ID3D12Device4::CreateReservedResource1 method (d3d12.h)

Article
10/20/2021

Creates a resource (optionally for a protected session) that is reserved, and not yet mapped to any pages in a heap. Also see ID3D12Device::CreateReservedResource.

Note

Only tiles from heaps created with the same protected resource session can be mapped into a protected reserved resource.

Syntax

HRESULT CreateReservedResource1(
  [in]            const D3D12_RESOURCE_DESC      *pDesc,
  [in]            D3D12_RESOURCE_STATES          InitialState,
  [in, optional]  const D3D12_CLEAR_VALUE        *pOptimizedClearValue,
  [in, optional]  ID3D12ProtectedResourceSession *pProtectedSession,
  [in]            REFIID                         riid,
  [out, optional] void                           **ppvResource
);

Parameters

[in] pDesc

Type: const D3D12_RESOURCE_DESC*

A pointer to a D3D12_RESOURCE_DESC structure that describes the resource.

[in] InitialState

Type: D3D12_RESOURCE_STATES

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

[in, optional] 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.

[in, optional] 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.

[in] riid

Type: REFIID

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

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.

[out, optional] 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.

Remarks

CreateReservedResource is equivalent to D3D11_RESOURCE_MISC_TILED in Direct3D 11. It creates a resource with virtual memory only, no backing store.

You need to map the resource to physical memory (that is, to a heap) using CopyTileMappings and UpdateTileMappings.

These resource types can only be created when the adapter supports tiled resource tier 1 or greater. The tiled resource tier defines the behavior of accessing a resource that is not mapped to a heap.

Requirements

Requirement	Value
Minimum supported client	Windows 10 Build 20348
Minimum supported server	Windows 10 Build 20348
Target Platform	Windows
Header	d3d12.h
Library	d3d12.lib
DLL	d3d12.dll