D3D12CreateDevice 函数 (d3d12.h)

项目
02/29/2024

创建表示显示适配器的设备。

语法

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

参数

[in, optional] pAdapter

类型： IUnknown*

指向创建设备时要使用的视频适配器的指针。传递 NULL 以使用默认适配器，这是 IDXGIFactory1：：EnumAdapters 枚举的第一个适配器。

注意不要在应用程序中混合使用 DXGI 1.0 (IDXGIFactory) 和 DXGI 1.1 (IDXGIFactory1) 。在应用程序中使用 IDXGIFactory 或 IDXGIFactory1，但不能同时使用 IDXGIFactory。

MinimumFeatureLevel

类型： D3D_FEATURE_LEVEL

成功创建设备所需的最低 D3D_FEATURE_LEVEL 。

[in] riid

类型： REFIID

设备接口的全局唯一标识符 (GUID) 。此参数和 ppDevice 可以使用单个宏 IID_PPV_ARGS进行寻址。

[out, optional] ppDevice

类型： void**

指向接收指向设备的指针的内存块的指针。传递 NULL 以测试设备创建是否成功，但不实际创建设备。如果传递 NULL 且设备创建成功，则返回 S_FALSE 。

返回值

类型： HRESULT

此方法可以返回 Direct3D 12 返回代码之一。

可能的返回值包括为 CreateDXGIFactory1 和 IDXGIFactory：：EnumAdapters 记录的值。

如果 ppDevice 为 NULL 且函数成功，则返回 S_FALSE ，而不是 S_OK。

注解

Direct3D 12 设备是每个适配器的单一实例。如果给定适配器的当前进程中已存在 Direct3D 12 设备，则对 D3D12CreateDevice 的后续调用将返回现有设备。如果当前 Direct3D 12 设备处于删除状态 (即 ID3D12Device：：GetDeviceRemovedReason 返回失败的 HRESULT) ，则 D3D12CreateDevice 将失败，而不是返回现有设备。两个适配器的相同性 (即，它们具有相同的标识) 通过比较其 LUID（而不是指针）来确定。

为了确保选取支持 D3D12 的第一个适配器，请使用以下代码。

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();
    }
}

函数签名PFN_D3D12_CREATE_DEVICE作为 typedef 提供，因此可以使用动态链接技术 (GetProcAddress) 而不是静态链接。

可以使用宏获取 __uuidof()设备接口的 REFIID 或 GUID。例如， __uuidof (ID3D12Device) 将获取设备接口的 GUID 。

示例

创建基于硬件的设备，除非指示创建 WARP 软件设备。

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)
        ));
}

请参阅 D3D12 参考中的示例代码。