D3D12CreateDevice function (d3d12.h)

Article
07/27/2022

Creates a device that represents the display adapter.

Syntax

HRESULT D3D12CreateDevice(
  [in, optional]  IUnknown          *pAdapter,
                  D3D_FEATURE_LEVEL MinimumFeatureLevel,
  [in]            REFIID            riid,
  [out, optional] void              **ppDevice
);

Parameters

[in, optional] pAdapter

Type: IUnknown*

A pointer to the video adapter to use when creating a device. Pass NULL to use the default adapter, which is the first adapter that is enumerated by IDXGIFactory1::EnumAdapters.

Note Don't mix the use of DXGI 1.0 (IDXGIFactory) and DXGI 1.1 (IDXGIFactory1) in an application. Use IDXGIFactory or IDXGIFactory1, but not both in an application.

MinimumFeatureLevel

Type: D3D_FEATURE_LEVEL

The minimum D3D_FEATURE_LEVEL required for successful device creation.

[in] riid

Type: REFIID

The globally unique identifier (GUID) for the device interface. This parameter, and ppDevice, can be addressed with the single macro IID_PPV_ARGS.

[out, optional] ppDevice

Type: void**

A pointer to a memory block that receives a pointer to the device. Pass NULL to test if device creation would succeed, but to not actually create the device. If NULL is passed and device creation would succeed, S_FALSE is returned.

Return value

Type: HRESULT

This method can return one of the Direct3D 12 Return Codes.

Possible return values include those documented for CreateDXGIFactory1 and IDXGIFactory::EnumAdapters.

If ppDevice is NULL and the function succeeds, S_FALSE is returned, rather than S_OK.

Remarks

Direct3D 12 devices are singletons per adapter. If a Direct3D 12 device already exists in the current process for a given adapter, then a subsequent call to D3D12CreateDevice returns the existing device. If the current Direct3D 12 device is in a removed state (that is, ID3D12Device::GetDeviceRemovedReason returns a failing HRESULT), then D3D12CreateDevice fails instead of returning the existing device. The sameness of two adapters (that is, they have the same identity) is determined by comparing their LUIDs, not their pointers.

In order to be sure to pick up the first adapter that supports D3D12, use the following code.

void GetHardwareAdapter(IDXGIFactory4* pFactory, IDXGIAdapter1** ppAdapter)
{
    *ppAdapter = nullptr;
    for (UINT adapterIndex = 0; ; ++adapterIndex)
    {
        IDXGIAdapter1* pAdapter = nullptr;
        if (DXGI_ERROR_NOT_FOUND == pFactory->EnumAdapters1(adapterIndex, &pAdapter))
        {
            // No more adapters to enumerate.
            break;
        } 

        // Check to see if the adapter supports Direct3D 12, but don't create the
        // actual device yet.
        if (SUCCEEDED(D3D12CreateDevice(pAdapter, D3D_FEATURE_LEVEL_11_0, _uuidof(ID3D12Device), nullptr)))
        {
            *ppAdapter = pAdapter;
            return;
        }
        pAdapter->Release();
    }
}

The function signature PFN_D3D12_CREATE_DEVICE is provided as a typedef, so that you can use dynamic linking techniques (GetProcAddress) instead of statically linking.

The REFIID, or GUID, of the interface to a device can be obtained by using the __uuidof() macro. For example, __uuidof(ID3D12Device) will get the GUID of the interface to a device.

Examples

Create a hardware based device, unless instructed to create a WARP software device.

ComPtr<IDXGIFactory4> factory;
ThrowIfFailed(CreateDXGIFactory1(IID_PPV_ARGS(&factory)));

if (m_useWarpDevice)
{
    ComPtr<IDXGIAdapter> warpAdapter;
    ThrowIfFailed(factory->EnumWarpAdapter(IID_PPV_ARGS(&warpAdapter)));

    ThrowIfFailed(D3D12CreateDevice(
        warpAdapter.Get(),
        D3D_FEATURE_LEVEL_11_0,
        IID_PPV_ARGS(&m_device)
        ));
}
else
{
    ComPtr<IDXGIAdapter1> hardwareAdapter;
    GetHardwareAdapter(factory.Get(), &hardwareAdapter);

    ThrowIfFailed(D3D12CreateDevice(
        hardwareAdapter.Get(),
        D3D_FEATURE_LEVEL_11_0,
        IID_PPV_ARGS(&m_device)
        ));
}

Refer to the Example Code in the D3D12 Reference.

Requirements

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

Share via