Fungsi D3D12CreateDevice (d3d12.h)

Artikel
08/23/2023

Membuat perangkat yang mewakili adaptor tampilan.

Sintaks

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

Parameter

[in, optional] pAdapter

Jenis: IUnknown*

Penunjuk ke adaptor video untuk digunakan saat membuat perangkat. Teruskan NULL untuk menggunakan adaptor default, yang merupakan adaptor pertama yang dijumlahkan oleh IDXGIFactory1::EnumAdapters.

Catatan Jangan mencampur penggunaan DXGI 1.0 (IDXGIFactory) dan DXGI 1.1 (IDXGIFactory1) dalam aplikasi. Gunakan IDXGIFactory atau IDXGIFactory1, tetapi tidak keduanya dalam aplikasi.

MinimumFeatureLevel

Jenis: D3D_FEATURE_LEVEL

D3D_FEATURE_LEVEL minimum yang diperlukan untuk pembuatan perangkat yang berhasil.

[in] riid

Jenis: REFIID

Pengidentifikasi unik global (GUID) untuk antarmuka perangkat. Parameter ini, dan ppDevice, dapat diatasi dengan IID_PPV_ARGS makro tunggal.

[out, optional] ppDevice

Jenis: batal**

Penunjuk ke blok memori yang menerima penunjuk ke perangkat. Lewati NULL untuk menguji apakah pembuatan perangkat akan berhasil, tetapi untuk tidak benar-benar membuat perangkat. Jika NULL diteruskan dan pembuatan perangkat akan berhasil, S_FALSE dikembalikan.

Mengembalikan nilai

Jenis: HRESULT

Metode ini dapat mengembalikan salah satu Kode Pengembalian Direct3D 12.

Kemungkinan nilai pengembalian termasuk yang didokumenkan untuk CreateDXGIFactory1 dan IDXGIFactory::EnumAdapters.

Jika ppDeviceadalah NULL dan fungsi berhasil, S_FALSE dikembalikan, bukan S_OK.

Keterangan

Perangkat Direct3D 12 adalah singleton per adaptor. Jika perangkat Direct3D 12 sudah ada dalam proses saat ini untuk adaptor tertentu, maka panggilan berikutnya ke D3D12CreateDevice mengembalikan perangkat yang ada. Jika perangkat Direct3D 12 saat ini dalam status dihapus (yaitu, ID3D12Device::GetDeviceRemovedReason mengembalikan HRESULT yang gagal), maka D3D12CreateDevice gagal alih-alih mengembalikan perangkat yang ada. Kesamaan dua adaptor (yaitu, mereka memiliki identitas yang sama) ditentukan dengan membandingkan LUID mereka, bukan pointer mereka.

Untuk memastikan untuk mengambil adaptor pertama yang mendukung D3D12, gunakan kode berikut.

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

Tanda tangan fungsi PFN_D3D12_CREATE_DEVICE disediakan sebagai typedef, sehingga Anda dapat menggunakan teknik penautan dinamis (GetProcAddress) alih-alih menautkan secara statis.

REFIID, atau GUID, antarmuka ke perangkat dapat diperoleh dengan menggunakan __uuidof() makro. Misalnya, __uuidof(ID3D12Device) akan mendapatkan GUID antarmuka ke perangkat.

Contoh

Buat perangkat berbasis perangkat keras, kecuali diinstruksikan untuk membuat perangkat lunak 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)
        ));
}

Lihat Contoh Kode dalam Referensi D3D12.