ID3D11On12Device2::UnwrapUnderlyingResource method (d3d11on12.h)

Article
10/13/2021

Unwraps a Direct3D 11 resource object, and retrieves it as a Direct3D 12 resource object.

Syntax

HRESULT UnwrapUnderlyingResource(
  [in]  ID3D11Resource     *pResource11,
  [in]  ID3D12CommandQueue *pCommandQueue,
  [in]  REFIID             riid,
  [out] void               **ppvResource12
);

Parameters

[in] pResource11

Type: ID3D11Resource*

The Direct3D 11 resource object to unwrap.

[in] pCommandQueue

Type: ID3D12CommandQueue*

The command queue on which your application plans to use the resource. Any pending work accessing the resource causes fence waits to be scheduled on this queue. You can then queue further work on this queue, including a signal on a caller-owned fence.

[in] riid

Type: REFIID

A reference to the globally unique identifier (GUID) of the interface that you wish to be returned in ppvResource12.

[out] ppvResource12

Type: void**

A pointer to a memory block that receives a pointer to the Direct3D 12 resource.

Return value

Type: HRESULT

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

Remarks

The resource is transitioned to D3D12_RESOURCE_STATE_COMMON (if it wasn't already in that state), and appropriate waits are inserted into the command queue (pCommandQueue).

There are some restrictions on what can be unwrapped: no keyed mutex resources, no GDI-compatible resources, and no buffers. However, you can use UnwrapUnderlyingResource to unwrap resources created through the ID3D11On12Device::CreateWrappedResource method, as well as resources created through ID3D11Device::CreateTexture2D.

In general, you must return the object to Direct3D11on12 before using it again in Direct3D 11 (see ID3D11On12Device2::ReturnUnderlyingResource).

You can also use UnwrapUnderlyingResource to unwrap a swapchain buffer. You must also return the resource to Direct3D11on12 before calling Present (or otherwise using the resource).

Unwrapping a resource checks out the resource from the Direct3D11On12 translation layer. You may not schedule any translation layer usage (through either version of the API) while the resource is checked out. Check the resource back in (also known as returning the resource) with ID3D11On12Device2::ReturnUnderlyingResource.

UnwrapUnderlyingResource doesn't flush, and it may schedule GPU work. You should flush after calling UnwrapUnderlyingResource if you externally wait for completion.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 2004 (10.0; Build 19041)
Minimum supported server	Windows Server, version 2004 (10.0; Build 19041)
Header	d3d11on12.h
Library	D3D11.lib
DLL	D3D11.dll

Share via