Función D3D12CreateDevice (d3d12.h)

Artículo
08/23/2023

Crea un dispositivo que representa el adaptador de pantalla.

Sintaxis

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

Parámetros

[in, optional] pAdapter

Tipo: IUnknown*

Puntero al adaptador de vídeo que se va a usar al crear un dispositivo. Pase NULL para usar el adaptador predeterminado, que es el primer adaptador enumerado por IDXGIFactory1::EnumAdapters.

Nota No combine el uso de DXGI 1.0 (IDXGIFactory) y DXGI 1.1 (IDXGIFactory1) en una aplicación. Use IDXGIFactory o IDXGIFactory1, pero no ambos en una aplicación.

MinimumFeatureLevel

Tipo: D3D_FEATURE_LEVEL

El D3D_FEATURE_LEVEL mínimo necesario para la creación correcta del dispositivo.

[in] riid

Tipo: REFIID

Identificador único global (GUID) de la interfaz del dispositivo. Este parámetro, y ppDevice, se pueden solucionar con la única macro IID_PPV_ARGS.

[out, optional] ppDevice

Tipo: void**

Puntero a un bloque de memoria que recibe un puntero al dispositivo. Pase NULL para probar si la creación del dispositivo se realizaría correctamente, pero no crear realmente el dispositivo. Si se pasa NULL y la creación del dispositivo se realiza correctamente, se devuelve S_FALSE .

Valor devuelto

Tipo: HRESULT

Este método puede devolver uno de los códigos de retorno de Direct3D 12.

Entre los valores devueltos posibles se incluyen los documentados para CreateDXGIFactory1 e IDXGIFactory::EnumAdapters.

Si ppDevice es NULL y la función se realiza correctamente, se devuelve S_FALSE , en lugar de S_OK.

Comentarios

Los dispositivos Direct3D 12 son singletons por adaptador. Si ya existe un dispositivo Direct3D 12 en el proceso actual para un adaptador determinado, una llamada posterior a D3D12CreateDevice devuelve el dispositivo existente. Si el dispositivo Direct3D 12 actual está en un estado quitado (es decir, ID3D12Device::GetDeviceRemovedReason devuelve un HRESULT con error), D3D12CreateDevice produce un error en lugar de devolver el dispositivo existente. La misma exactitud de dos adaptadores (es decir, tienen la misma identidad) se determina comparando sus LUID, no sus punteros.

Para asegurarse de seleccionar el primer adaptador que admita D3D12, use el código siguiente.

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 de función PFN_D3D12_CREATE_DEVICE se proporciona como definición de tipo, para que pueda usar técnicas de vinculación dinámica (GetProcAddress) en lugar de vincular estáticamente.

El REFIID, o GUID, de la interfaz a un dispositivo se puede obtener mediante la __uuidof() macro . Por ejemplo, __uuidof(ID3D12Device) obtendrá el GUID de la interfaz en un dispositivo.

Ejemplos

Cree un dispositivo basado en hardware, a menos que se indique que cree un dispositivo de 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)
        ));
}

Consulte el código de ejemplo en la referencia D3D12.