PFND3DDDI_ALLOCATECB fungsi panggilan balik (d3dumddi.h)

Artikel
02/23/2024

Fungsi pfnAllocateCb mengalokasikan memori sistem atau video.

Sintaks

PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;

HRESULT Pfnd3dddiAllocatecb(
  [in] HANDLE hDevice,
       D3DDDICB_ALLOCATE *unnamedParam2
)
{...}

Parameter

[in] hDevice

Handel ke perangkat tampilan (konteks grafis).

unnamedParam2

pData [masuk, keluar]

Penunjuk ke struktur D3DDDICB_ALLOCATE yang menjelaskan alokasi.

Menampilkan nilai

pfnAllocateCb mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
S_OK	Memori berhasil dialokasikan.
E_INVALIDARG	Parameter divalidasi dan ditentukan salah.
E_OUTOFMEMORY	pfnAllocateCb tidak dapat mengalokasikan memori yang diperlukan untuk menyelesaikannya.
D3DERR_OUTOFVIDEOMEMORY	pfnAllocateCb tidak dapat diselesaikan karena memori video yang tidak mencukuum. Manajer memori video mencoba memvirtualisasi memori video; namun, jika virtualisasi gagal (seperti, ketika ruang alamat virtual habis), manajer memori mungkin mengembalikan kode kesalahan ini.
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb tidak dapat memulai panggilan ke fungsi DxgkDdiCreateAllocation driver miniport karena terjadi penghentian Plug and Play (PnP) atau peristiwa Deteksi dan Pemulihan Waktu Habis (TDR). Fungsi driver tampilan mode pengguna yang disebut pfnAllocateCb (biasanya, fungsi CreateResource, CreateResource(D3D10), atau CreateResource(D3D11) harus mengembalikan kode kesalahan ini kembali ke runtime Direct3D. Direct3D Versi 9 Catatan: Untuk informasi selengkapnya tentang mengembalikan kode kesalahan, lihat Mengembalikan Kode Kesalahan yang Diterima dari Fungsi Runtime. Direct3D Versi 10 dan 11 Catatan: Jika fungsi driver tidak mengembalikan nilai (yaitu, memiliki VOID untuk jenis parameter pengembalian), fungsi driver memanggil fungsi pfnSetErrorCb untuk mengirim kode kesalahan kembali ke runtime. Untuk informasi selengkapnya tentang menangani kode kesalahan, lihat Menangani Kesalahan.

Fungsi ini mungkin juga mengembalikan nilai HRESULT lainnya.

Keterangan

Driver tampilan mode pengguna memanggil pfnAllocateCb untuk mengalokasikan memori sistem atau video (juga dikenal sebagai alokasi). Subsistem kernel grafis Microsoft DirectX (Dxgkrnl.sys) kemudian memanggil fungsi DxgkDdiCreateAllocation driver miniport tampilan untuk menginterpretasikan dan menyimpan data privat yang diteruskan dalam permintaan pfnAllocateCb . Driver miniport tampilan mengembalikan informasi dari panggilan DxgkDdiCreateAllocation yang digunakan manajer memori video (yang merupakan bagian dari Dxgkrnl.sys) untuk benar-benar mengalokasikan memori.

Driver tampilan mode pengguna biasanya membuat alokasi sebagai respons terhadap panggilan ke fungsi CreateResource, CreateResource(D3D10), atau CreateResource(D3D11). Namun, driver tampilan mode pengguna dapat membuat alokasi kapan saja--misalnya, ketika mode pengguna menampilkan fungsi CreateDevice, atau CreateDevice (D3D10) menciptakan area scratch-pad dalam memori video.

Driver tampilan mode pengguna dapat membuat jenis alokasi berikut:

Alokasi memori sistem di mana runtime Microsoft Direct3D melakukan pra-alokasi memori sistem. Dalam situasi ini, driver tampilan mode pengguna tidak dapat mengatur perataan atau parameter lainnya. Jika driver tampilan mode pengguna memerlukan memori sistem yang telah dialokasikan sebelumnya yang dapat diakses oleh perangkat keras, itu memanggil pfnAllocateCb. Runtime Direct3D mengembalikan penunjuk memori sistem di anggota pSystemMem dari struktur D3DDDI_ALLOCATIONINFO untuk elemen dalam anggota pAllocationInfo dari struktur D3DDDICB_ALLOCATE yang ditunjukkan oleh pData. Jika driver tampilan mode pengguna tidak memerlukan memori sistem yang telah dialokasikan sebelumnya yang dapat diakses oleh perangkat keras, itu tidak boleh memanggil pfnAllocateCb untuk jenis memori ini.
Alokasi memori sistem dan video tempat driver tampilan mode pengguna dapat berpartisipasi dalam pembuatan.

Ketika driver mencoba membuat beberapa alokasi, driver dapat mengaitkan semua alokasi dengan sumber daya induk (misalnya, saat membuat rantai balik di mana setiap backbuffer adalah alokasi individu). Driver dapat melakukan asosiasi seperti itu dengan mengatur anggota hResource dari struktur D3DDDICB_ALLOCATE yang diarahkan oleh pData ke nilai yang diteruskan ke fungsi CreateResource, CreateResource(D3D10) driver, atau CreateResource (D3D11). Sebagai tanggapan, runtime Direct3D mengembalikan handel sumber daya mode kernel (yang merupakan jenis data D3DKMT_HANDLE) di anggota D3DDDICB_ALLOCATE hKMResource . Driver tampilan mode pengguna kemudian dapat menyisipkan handel sumber daya mode kernel ini di aliran perintah untuk digunakan oleh driver miniport tampilan.

Driver miniport tampilan dapat memanggil fungsi DxgkCbGetHandleData pada handel sumber daya mode kernel ini (biasanya dalam fungsi DxgkDdiRender ) untuk mendapatkan data pribadi yang terkait dengan sumber daya, atau driver miniport tampilan dapat memanggil fungsi DxgkCbEnumHandleChildren untuk mendapatkan semua alokasi yang terkait dengan sumber daya. Driver miniport tampilan juga dapat memanggil fungsi DxgkCbGetHandleParent untuk mendapatkan handel sumber daya mode kernel induk dari handel alokasi anak.

Perhatikan bahwa jika anggota hResource D3DDDICB_ALLOCATE diatur ke NULL saat driver tampilan mode pengguna memanggil pfnAllocateCb, alokasi dikaitkan dengan perangkat alih-alih dengan sumber daya. Driver hanya dapat menentukan bahwa perbedaannya semantik. Mengaitkan alokasi dengan sumber daya bersifat opsional tetapi direkomendasikan untuk tujuan penelusuran kesalahan dan diagnostik.

Catatan Direct3D Versi 9: Untuk informasi selengkapnya tentang membuat dan menghancurkan sumber daya, lihat Menangani Pembuatan dan Penghancuran Sumber Daya.

Catatan Direct3D Versi 11: Untuk informasi selengkapnya tentang cara driver memanggil pfnAllocateCb, lihat Perubahan dari Direct3D 10.

Contoh kode berikut menunjukkan cara mengalokasikan memori untuk sumber daya.

    D3DDDICB_ALLOCATE           allocCB;
    D3DDDI_ALLOCATIONINFO       allocInfo;
    HRESULT                     hr;
    memset(&allocInfo,   0, sizeof(allocInfo));
    memset(&allocCB,     0, sizeof(allocCB));
    // Set the VidPN source ID for the primary and fullscreen back buffer
    if (m_dwCurResCaps.Primary) {
        allocInfo.Flags.Primary = TRUE;
        allocInfo.VidPnSourceId = m_VidPnSourceId;
    }
    // Check if the allocation is in system memory
    if (pSysMem) {
        allocInfo.pSystemMem = pSysMem;
    }
    // Use the runtime handle of the resource being created
    // NOTE: This is critical for supporting a shared resource
    allocCB.hResource = m_hCurResRuntime;

    allocCB.NumAllocations = 1;
    allocCB.pAllocationInfo = &allocInfo;

    hr = m_d3dCallbacks.pfnAllocateCb(m_hD3D, &allocCB);

    if (FAILED(hr)) {
        allocInfo.hAllocation = NULL;
    }
    else {
        *phAllocation = allocInfo.hAllocation;
    }

    return (hr);

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows Vista dan versi yang lebih baru dari sistem operasi Windows.
Target Platform	Desktop
Header	d3dumddi.h (termasuk D3dumddi.h)