DXGKDDI_PRESENT fungsi panggilan balik (d3dkmddi.h)

Artikel
03/08/2023

Fungsi DxgkDdiPresent menyalin konten dari alokasi sumber ke permukaan utama (dan terkadang ke alokasi memori sistem di luar layar).

Sintaks

DXGKDDI_PRESENT DxgkddiPresent;

NTSTATUS DxgkddiPresent(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_PRESENT pPresent
)
{...}

Parameter

[in] hContext

Handel ke konteks perangkat untuk informasi penyalinan. Fungsi DxgkDdiCreateContext driver miniport tampilan sebelumnya mengembalikan handel ini di anggota hContext dari struktur DXGKARG_CREATECONTEXT yang ditunjukkan parameter pCreateContext dari DxgkDdiCreateContext .

Jika driver tidak mendukung pembuatan konteks, subsistem kernel grafis Microsoft DirectX menggantikan handel ke konteks dengan handel ke perangkat. Fungsi DxgkDdiCreateDevice driver miniport tampilan sebelumnya mengembalikan handel perangkat di anggota hDevice dari struktur DXGKARG_CREATEDEVICE yang ditunjukkan oleh parameter pCreateDevice dari DxgkDdiCreateDevice .

[in/out] pPresent

Penunjuk ke struktur DXGKARG_PRESENT yang berisi informasi tentang operasi salin.

Menampilkan nilai

DxgkDdiPresent mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	DxgkDdiPresent berhasil menyalin konten.
STATUS_NO_MEMORY atau STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent tidak dapat mengalokasikan memori yang diperlukan untuk menyelesaikannya.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Buffer akses memori langsung (DMA) saat ini habis.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	Driver miniport tampilan mendeteksi transfer blok bit (bitblt) untuk konversi warna yang tidak dapat dilakukan perangkat. Runtime Microsoft Direct3D mencegah aplikasi dilanjutkan, dan aplikasi menerima kegagalan untuk menyalin konten.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent mendeteksi instruksi nonprivileged (yaitu, instruksi yang mengakses memori di luar hak istimewa dari proses unit pemrosesan pusat [CPU] saat ini).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent mendeteksi instruksi yang tidak dapat didukung oleh perangkat keras grafis.
STATUS_INVALID_HANDLE	DxgkDdiPresent mendeteksi handel yang tidak valid di buffer perintah.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Driver miniport tampilan mendeteksi kesalahan dalam aliran DMA. Perangkat konteks grafis ditempatkan dalam status hilang jika driver mengembalikan kode kesalahan ini.

Keterangan

Subsistem kernel grafis DirectX memanggil fungsi DxgkDdiPresent driver miniport tampilan untuk menyalin konten dari alokasi sumber biasanya ke permukaan utama. (Fungsi ini juga dapat menyalin konten ke alokasi memori sistem di luar layar.) Karena permukaan utama didefinisikan secara longgar, DxgkDdiPresent dapat diimplementasikan untuk skenario berikut:

Tergantung pada posisi jendela, fungsi DxgkDdiPresent harus dilakukan di berbagai primari yang dapat berada di adaptor yang sama atau di berbagai adaptor.
Primer berada di monitor jarak jauh dan diakses melalui klien layanan terminal atau Microsoft NetMeeting.
Peralihan mode baru-baru ini terjadi dan format utama berbeda dari format sumber, sehingga konversi warna diperlukan. Selain itu, operasi DxgkDdiPresent dapat diklip karena pengklipan dan pemesanan jendela.

Karena skenario sebelumnya dapat berubah secara asinkron, driver tampilan mode pengguna tidak dapat mengompilasi instruksi perangkat keras untuk fungsi DxgkDdiPresent driver miniport tampilan terlebih dahulu. Driver miniport tampilan harus membuat perintah perangkat keras untuk operasi DxgkDdiPresent yang sebenarnya, dan harus ditempatkan dalam buffer DMA output. Setelah fungsi DxgkDdiPresent driver miniport tampilan dipanggil untuk menghasilkan buffer DMA, sistem operasi menjamin bahwa perubahan skenario tidak akan terjadi sebelum buffer tersebut dirender.

Driver miniport tampilan tidak diperlukan untuk mengetahui secara spesifik skenario sebelumnya selama driver mendukung abstraksi berikut:

Dalam operasi salin dari sumber memori video ke tujuan memori video atau sistem utama, salinan dari sumber memori sistem di luar layar ke tujuan utama, salinan dari dan ke primer, atau salinan dari sumber utama ke tujuan memori sistem di luar layar, sumber ditentukan oleh anggota hDeviceSpecificAllocation dari elemen array pAllocationList[DXGK_PRESENT_SOURCE_INDEX] dari struktur DXGKARG_PRESENT yang pPresentents parameter DxgkDdiPresent menunjuk ke. Tujuan, yang merupakan primer perangkat saat ini atau alokasi memori sistem di luar layar, ditentukan oleh anggota hDeviceSpecificAllocation dari elemen array pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] dari DXGKARG_PRESENT. Jika tujuan sama dengan sumber (yaitu, tujuan == sumber), operasi salin adalah transfer bit-block layar-ke-layar (bitblt). Oleh karena itu, subsistem grafis mengatur sumber dan tujuan ke nilai berikut:
- destination != NULL (yaitu, destination == nonNULL)
- source != NULL (yaitu, source == nonNULL)
Dalam memori video membalik dari alokasi saat ini ke alokasi lain, sumber dapat ditentukan oleh sistem operasi dan diatur dalam anggota hDeviceSpecificAllocation dari elemen array pAllocationList[DXGK_PRESENT_SOURCE_INDEX] dari DXGKARG_PRESENT. Subsistem grafik mengatur sumber dan tujuan ke nilai berikut:
- destination == NULL
- source != NULL (yaitu, source == nonNULL)
Catatan Flip no-op dapat dilakukan dari alokasi sumber yang sama dengan alokasi yang saat ini dipindai. Flip no-op digunakan untuk menyisipkan antrean menunggu kosong vertikal di aliran penyajian. Driver miniport tampilan harus memasukkan perintah balik perangkat keras seolah-olah membalik ke alokasi lain.
Dalam operasi pengisian warna ke permukaan utama, tidak ada alokasi sumber yang diperlukan dan tujuannya adalah handel alokasi utama yang ditentukan oleh anggota hDeviceSpecificAllocation dari elemen array pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] dari DXGKARG_PRESENT. Anggota Warna DXGKARG_PRESENT biasanya dalam format D3DDDIFMT_A8R8G8B8 dari jenis enumerasi D3DDDIFORMAT . Namun, ketika format utama dipalsukan RGB, Warna berisi indeks palet. Oleh karena itu, subsistem grafis mengatur sumber dan tujuan ke nilai berikut:
- destination != NULL (yaitu, destination == nonNULL)
- source == NULL

Agar semua skenario DxgkDdiPresent beroperasi dengan benar, fungsi DxgkDdiCreateDevice driver miniport tampilan harus mengatur anggota DmaBufferSize dari struktur DXGK_DEVICEINFO menjadi cukup besar untuk menahan perintah perangkat keras yang diperlukan untuk menyajikan setidaknya satu persegi reCT ke tampilan atau target di luar layar. Namun, fungsi DxgkDdiPresent driver dapat mengembalikan STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER jika jumlah subrektangle dalam skenario DxgkDdiPresent menguras buffer DMA saat ini dan driver memerlukan buffer DMA lain untuk melanjutkan.

Subsistem grafis kemudian memperoleh buffer DMA baru dan memanggil fungsi DxgkDdiPresent driver lagi dengan daftar struktur RECT yang sama dengan panggilan DxgkDdiPresent sebelumnya. Driver harus menggunakan anggota MultipassOffset dari struktur DXGKARG_PRESENT yang diarahkan oleh pPresent untuk merekam jumlah kemajuan yang dibuat dalam menyelesaikan daftar RECT dalam panggilan sebelumnya ke DxgkDdiPresent sehingga driver dapat melanjutkan dari mana ia berhenti dengan buffer DMA baru. Ketika fungsi DxgkDdiPresent driver menyelesaikan daftar struktur RECT, fungsi mengembalikan STATUS_SUCCESS.

Selain menghasilkan buffer DMA, driver miniport tampilan harus menghasilkan daftar lokasi patch yang menunjukkan berbagai offset dalam buffer DMA yang harus di-patch nanti ketika alamat fisik untuk alokasi diketahui. Terkadang, manajer memori video memberi driver informasi pra-patch (yaitu, alamat fisik terakhir yang diketahui untuk sumber dan tujuan) dalam daftar alokasi.

Ketika manajer memori video memberikan informasi ini, driver harus menghasilkan buffer DMA dengan menentukan bahwa alamat fisik ini adalah alamat akhir yang akan disediakan subsistem kernel grafis DirectX. Subsistem grafis mungkin tidak memanggil fungsi DxgkDdiPatch pada buffer DMA untuk menambalnya lagi nanti. Oleh karena itu, driver harus menggunakan informasi pra-patch untuk menghasilkan buffer DMA dengan benar. Informasi pra-patch disediakan untuk elemen N ketika anggota SegmentId dari elemen Ndari array pAllocationListDXGKARG_PRESENT bukan nol.

Catatan Meskipun fungsi DxgkDdiPresent driver melakukan pra-patch pada buffer DMA, driver masih harus menyisipkan semua referensi ke alokasi ke dalam daftar lokasi patch output yang ditentukan anggota pPatchLocationListOut dari DXGKARG_PRESENT . Driver harus menyisipkan referensi ini karena alamat alokasi mungkin berubah sebelum buffer DMA dikirimkan ke GPU; oleh karena itu, subsistem kernel grafis DirectX akan memanggil fungsi DxgkDdiPatch untuk mengirimkan ulang buffer DMA.

Jika driver mendukung rotasi (yaitu, melaporkan dukungan untuk mode yang diputar di anggota RotationSupport dari struktur D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION dalam panggilan ke fungsi DxgkDdiEnumVidPnCofuncModality ), driver harus dapat melakukan transfer blok bit yang diputar (bitblt) dari sumber ke tujuan. Ketika bendera Putar bit-field ditentukan dalam struktur DXGK_PRESENTFLAGS untuk anggota BenderaDXGKARG_PRESENT, driver harus menerapkan rotasi seolah-olah beralih dari permukaan yang tidak diputar ke orientasi akhir sumber saat ini.

Alokasi utama sumber ditentukan dalam fungsi DxgkDdiCommitVidPn . Jika beberapa jalur berasal dari sumber yang diberikan (mode kloning), driver miniport tampilan harus memastikan bahwa output diputar dengan benar mengingat mode rotasi jalur untuk target yang berbeda. Semua parameter yang disediakan ke DxgkDdiPresent adalah agnostik rotasi. Persegi panjang sumber dan target bisa menjadi seluruh layar saat klien memahaminya (misalnya, 768 x 1024).

Catatan Situasi ini tidak mengatasi aplikasi Direct3D layar penuh dalam mode diputar.

Jika driver miniport tampilan sebelumnya ditunjukkan, dalam panggilan ke fungsi DxgkDdiQueryAdapterInfo-nya , bahwa ia mendukung flip berbasis I/O (MMIO) yang dipetakan memori (dengan mengatur bendera bit-field FlipOnVSyncMmIo di anggota FlipCaps dari struktur DXGK_DRIVERCAPS ke TRUE), fungsi DxgkDdiPresent driver kemudian dipanggil dengan anggota pDmaBufferdari DXGKARG_PRESENT diatur ke NULL karena flip berbasis MMIO tidak memerlukan buffer DMA untuk berjalan pada GPU. Sebagai gantinya, fungsi DxgkDdiPresent driver harus memvalidasi permukaan sumber dan program membalik perangkat keras sesuai kebutuhan. Subsistem kernel grafis DirectX memanggil fungsi DxgkDdiSetVidPnSourceAddress driver untuk menjalankan jenis flip ini.

DxgkDdiPresent harus dibuat pageable.