Função D3D12CreateDevice (d3d12.h)

Artigo
02/26/2024

Cria um dispositivo que representa o adaptador de exibição.

Sintaxe

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

Parâmetros

[in, optional] pAdapter

Tipo: IUnknown*

Um ponteiro para o adaptador de vídeo a ser usado ao criar um dispositivo. Passe NULL para usar o adaptador padrão, que é o primeiro adaptador que é enumerado por IDXGIFactory1::EnumAdapters.

Nota Não misture o uso de DXGI 1.0 (IDXGIFactory) e DXGI 1.1 (IDXGIFactory1) em um aplicativo. Use IDXGIFactory ou IDXGIFactory1, mas não ambos em um aplicativo.

MinimumFeatureLevel

Tipo: D3D_FEATURE_LEVEL

O D3D_FEATURE_LEVEL mínimo necessário para a criação bem-sucedida do dispositivo.

[in] riid

Tipo: REFIID

O GUID (identificador global exclusivo) para a interface do dispositivo. Esse parâmetro e ppDevice podem ser abordados com a macro única IID_PPV_ARGS.

[out, optional] ppDevice

Tipo: void**

Um ponteiro para um bloco de memória que recebe um ponteiro para o dispositivo. Passe NULL para testar se a criação do dispositivo teria êxito, mas para não realmente criar o dispositivo. Se NULL for passado e a criação do dispositivo for bem-sucedida, S_FALSE será retornado.

Retornar valor

Tipo: HRESULT

Esse método pode retornar um dos códigos de retorno do Direct3D 12.

Os valores retornados possíveis incluem aqueles documentados para CreateDXGIFactory1 e IDXGIFactory::EnumAdapters.

Se ppDevice for NULL e a função for bem-sucedida, S_FALSE será retornado, em vez de S_OK.

Comentários

Os dispositivos Direct3D 12 são singletons por adaptador. Se um dispositivo Direct3D 12 já existir no processo atual para um determinado adaptador, uma chamada subsequente para D3D12CreateDevice retornará o dispositivo existente. Se o dispositivo Direct3D 12 atual estiver em um estado removido (ou seja, ID3D12Device::GetDeviceRemovedReason retornar um HRESULT com falha), D3D12CreateDevice falhará em vez de retornar o dispositivo existente. A mesmez de dois adaptadores (ou seja, eles têm a mesma identidade) é determinada comparando seus LUIDs, não seus ponteiros.

Para ter certeza de pegar o primeiro adaptador que dá suporte a D3D12, use o código a seguir.

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

A assinatura de função PFN_D3D12_CREATE_DEVICE é fornecida como um typedef, para que você possa usar técnicas de vinculação dinâmica (GetProcAddress) em vez de vincular estaticamente.

O REFIID, ou GUID, da interface para um dispositivo pode ser obtido usando a __uuidof() macro . Por exemplo, __uuidof(ID3D12Device) obterá o GUID da interface para um dispositivo.

Exemplos

Crie um dispositivo baseado em hardware, a menos que seja instruído a criar um 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 o Código de Exemplo na Referência D3D12.