Funzione D3D12CreateDevice (d3d12.h)

Articolo
08/23/2023

Crea un dispositivo che rappresenta l'adattatore di visualizzazione.

Sintassi

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

Parametri

[in, optional] pAdapter

Tipo: IUnknown*

Puntatore alla scheda video da usare durante la creazione di un dispositivo. Passare NULL per usare l'adapter predefinito, ovvero la prima scheda enumerata da IDXGIFactory1::EnumAdapters.

Nota Non combinare l'uso di DXGI 1.0 (IDXGIFactory) e DXGI 1.1 (IDXGIFactory1) in un'applicazione. Usare IDXGIFactory o IDXGIFactory1, ma non entrambi in un'applicazione.

MinimumFeatureLevel

Tipo: D3D_FEATURE_LEVEL

Minimo D3D_FEATURE_LEVEL necessario per la creazione di dispositivi con esito positivo.

[in] riid

Tipo: REFIID

Identificatore univoco globale (GUID) per l'interfaccia del dispositivo. Questo parametro e ppDevice possono essere risolti con la singola macro IID_PPV_ARGS.

[out, optional] ppDevice

Tipo: void**

Puntatore a un blocco di memoria che riceve un puntatore al dispositivo. Passare NULL per testare se la creazione del dispositivo avrà esito positivo, ma non creare effettivamente il dispositivo. Se NULL viene passato e la creazione del dispositivo avrà esito positivo, viene restituito S_FALSE .

Valore restituito

Tipo: HRESULT

Questo metodo può restituire uno dei codici restituiti Direct3D 12.

I valori restituiti possibili includono quelli documentati per CreateDXGIFactory1 e IDXGIFactory::EnumAdapters.

Se ppDevice è NULL e la funzione ha esito positivo, S_FALSE viene restituito anziché S_OK.

Commenti

I dispositivi Direct3D 12 sono singleton per scheda. Se un dispositivo Direct3D 12 esiste già nel processo corrente per una determinata scheda, una chiamata successiva a D3D12CreateDevice restituisce il dispositivo esistente. Se il dispositivo Direct3D 12 corrente si trova in uno stato rimosso, ovvero ID3D12Device::GetDeviceRemovedReason restituisce un errore HRESULT, D3D12CreateDevice non riesce anziché restituire il dispositivo esistente. La stessa somiglianza di due adattatori (ovvero, hanno la stessa identità) è determinata confrontando i loro ID, non i loro puntatori.

Per assicurarsi di selezionare la prima scheda che supporta D3D12, usare il codice seguente.

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

La firma della funzione PFN_D3D12_CREATE_DEVICE viene fornita come typedef, in modo che sia possibile usare tecniche di collegamento dinamico (GetProcAddress) anziché collegare staticamente.

È possibile ottenere il GUID REFIID o il GUID dell'interfaccia a un dispositivo usando la __uuidof() macro. Ad esempio, __uuidof(ID3D12Device) otterrà il GUID dell'interfaccia in un dispositivo.

Esempio

Creare un dispositivo basato su hardware, a meno che non venga indicato di creare un dispositivo software 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)
        ));
}

Fare riferimento al codice di esempio nel riferimento D3D12.