D3D12CreateDevice-Funktion (d3d12.h)

Artikel
08/23/2023

Erstellt ein Gerät, das die Grafikkarte darstellt.

Syntax

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

Parameter

[in, optional] pAdapter

Typ: IUnknown*

Ein Zeiger auf die Grafikkarte, die beim Erstellen eines Geräts verwendet werden soll. Übergeben Sie NULL , um den Standardadapter zu verwenden. Dabei handelt es sich um den ersten Adapter, der von IDXGIFactory1::EnumAdapters aufgezählt wird.

Hinweis Mischen Sie die Verwendung von DXGI 1.0 (IDXGIFactory) und DXGI 1.1 (IDXGIFactory1) in einer Anwendung nicht. Verwenden Sie IDXGIFactory oder IDXGIFactory1, aber nicht beides in einer Anwendung.

MinimumFeatureLevel

Typ: D3D_FEATURE_LEVEL

Die mindest D3D_FEATURE_LEVEL , die für die erfolgreiche Geräteerstellung erforderlich sind.

[in] riid

Typ: REFIID

Der globally unique Identifier (GUID) für die Geräteschnittstelle. Dieser Parameter und ppDevice können mit dem einzelnen Makro IID_PPV_ARGS adressiert werden.

[out, optional] ppDevice

Typ: void**

Ein Zeiger auf einen Speicherblock, der einen Zeiger auf das Gerät empfängt. Übergeben Sie NULL , um zu testen, ob die Geräteerstellung erfolgreich war, aber nicht, um das Gerät tatsächlich zu erstellen. Wenn NULL übergeben wird und die Geräteerstellung erfolgreich war, wird S_FALSE zurückgegeben.

Rückgabewert

Typ: HRESULT

Diese Methode kann einen der Direct3D 12-Rückgabecodes zurückgeben.

Mögliche Rückgabewerte sind die für CreateDXGIFactory1 und IDXGIFactory::EnumAdapters dokumentierten Werte.

Wenn ppDeviceNULL ist und die Funktion erfolgreich ist, wird S_FALSE zurückgegeben, anstatt S_OK.

Hinweise

Direct3D 12-Geräte sind Singletons pro Adapter. Wenn im aktuellen Prozess für einen bestimmten Adapter bereits ein Direct3D 12-Gerät vorhanden ist, gibt ein späterer Aufruf von D3D12CreateDevice das vorhandene Gerät zurück. Wenn sich das aktuelle Direct3D 12-Gerät in einem entfernten Zustand befindet (d. h. ID3D12Device::GetDeviceRemovedReason gibt ein fehlerhaftes HRESULT zurück), schlägt D3D12CreateDevice fehl, anstatt das vorhandene Gerät zurückzugeben. Die Gleichheit von zwei Adaptern (d. h. sie haben dieselbe Identität) wird durch den Vergleich ihrer LUIDs, nicht ihrer Zeiger, bestimmt.

Verwenden Sie den folgenden Code, um den ersten Adapter zu verwenden, der D3D12 unterstützt.

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

Die Funktionssignatur PFN_D3D12_CREATE_DEVICE wird als Typedef bereitgestellt, sodass Sie dynamische Verknüpfungstechniken (GetProcAddress) anstelle von statisch verknüpfen können.

Die REFIID oder GUID der Schnittstelle zu einem Gerät kann mithilfe des __uuidof() Makros abgerufen werden. Beispielsweise __uuidofruft (ID3D12Device) die GUID der Schnittstelle auf ein Gerät ab.

Beispiele

Erstellen Sie ein hardwarebasiertes Gerät, es sei denn, Sie müssen ein WARP-Softwaregerät erstellen.

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

Weitere Informationen finden Sie im Beispielcode in der D3D12-Referenz.