PDD_SURFCB_LOCK fungsi panggilan balik (ddrawint.h)

Artikel
08/23/2023

Fungsi panggilan balik DdLock mengunci area memori permukaan tertentu dan menyediakan pointer yang valid ke blok memori yang terkait dengan permukaan.

Sintaks

PDD_SURFCB_LOCK PddSurfcbLock;

DWORD PddSurfcbLock(
  PDD_LOCKDATA unnamedParam1
)
{...}

Parameter

unnamedParam1

Menunjuk ke struktur DD_LOCKDATA yang berisi informasi yang diperlukan untuk melakukan penguncian.

Nilai kembali

DdLock mengembalikan salah satu kode panggilan balik berikut:

Keterangan

DdLock harus mengatur anggota ddRVal dari struktur DD_LOCKDATA di lpLock ke DDERR_WASSTILLDRAWING dan mengembalikan DDHAL_DRIVER_HANDLED jika blit atau flip sedang berlangsung.

Kecuali ditentukan lain oleh anggota dwFlags dari DD_LOCKDATA, driver dapat mengembalikan penunjuk memori ke bagian atas permukaan di anggota lpSurfData dari DD_LOCKDATA. Jika driver perlu menghitung alamatnya sendiri untuk permukaan, driver dapat mengandalkan pointer yang diteruskan di anggota DD_LOCKDATA fpProcess sebagai penunjuk per proses ke pemetaan mode pengguna dari buffer bingkai yang dapat diakses DirectDraw.

Kunci tidak menyediakan akses eksklusif ke blok memori yang diminta; artinya, beberapa utas dapat mengunci permukaan yang sama pada saat yang sama. Adalah tanggung jawab aplikasi untuk menyinkronkan akses ke blok memori yang penunjuknya diperoleh.

Driver yang berjalan pada sistem operasi berbasis NT tidak boleh mengembalikan pointer ke memori sistem dari fungsi DdLock-nya kecuali fungsi DdCreateSurface driver yang sebelumnya dialokasikan memori tersebut dengan bendera PLEASE_ALLOC_USERMEM. Jika PLEASE_ALLOC_USERMEM tidak digunakan, aplikasi dapat menerima kesalahan setiap kali mereka mencoba mengakses memori tersebut. Lihat Implementasi DDLOCK_NOSYSLOCK Kernel NT untuk informasi selengkapnya.

DdLock dapat dipanggil dengan PDEV yang dinonaktifkan. PDEV dinonaktifkan atau diaktifkan dengan memanggil fungsi DrvAssertMode driver tampilan. Lihat Mengelola PDEV untuk informasi selengkapnya.

Implementasi DDLOCK_NOSYSLOCK Kernel NT

Aplikasi dapat menggunakan antarmuka pemrograman aplikasi (API) DirectDraw dan Direct3D untuk mendapatkan kunci durasi panjang pada sumber daya memori video. Kunci seperti itu disebut kunci "NOSYSLOCK". Kunci ini beroperasi secara berbeda dari kunci memori video biasa seperti yang dijelaskan dalam paragraf berikut.

Setelah runtime DirectDraw memanggil fungsi DdLock driver dengan bendera DDLOCK_NOSYSLOCK yang ditentukan dalam anggota dwFlags DD_LOCKDATA, runtime memeriksa pointer ke konten permukaan yang dikembalikan oleh driver. Alih-alih meneruskan penunjuk yang dikembalikan driver langsung ke aplikasi, runtime membuat pemetaan mode pengguna kedua memori video (baik lokal maupun nonlokal) dan menghitung alamat virtual yang setara dalam pemetaan tersebut. Alamat virtual ini dikenal sebagai penunjuk alias ke kunci memori. Runtime meneruskan penunjuk alias-lock ini ke aplikasi. Aplikasi ini menggunakan penunjuk alias-lock ini untuk membaca dan menulis langsung ke memori video. Baik aplikasi maupun driver tidak menyadari bahwa aplikasi tersebut menggunakan penunjuk memori terkunci yang berbeda.

Kemudian, pada waktu peralihan mode, runtime DirectDraw mencatat penunjuk alias-lock yang luar biasa. Alih-alih menunggu penunjuk alias-lock selesai--seperti halnya untuk kunci memori video biasa--runtime memetakan ulang pemetaan memori video mode pengguna dan memungkinkan pengalihan mode untuk melanjutkan. Runtime memetakan ulang pemetaan mode pengguna ke satu halaman dummy; aplikasi terus membaca dan menulis ke halaman dummy tersebut, jika tidak, tidak menyadari perubahan apa pun. Runtime kemudian harus membersihkan penunjuk alias-lock dengan memanggil fungsi DdUnlock driver. Runtime dapat membersihkan penunjuk alias-lock karena aplikasi tidak lagi menulis ke dalam memori video. Karena pembersihan ini terjadi pada waktu peralihan mode, langkah selanjutnya dalam urutan adalah kehilangan permukaan, yang berarti menghancurkan objek per permukaan driver. Dengan kata lain, runtime memanggil fungsi DdDestroySurface driver untuk semua permukaan, termasuk permukaan yang terus dipertimbangkan aplikasi sebagai terkunci. Bahkan, aplikasi terus membaca dan menulis ke halaman dummy memori sistem.

Seluruh proses ini hanya berfungsi jika penunjuk memori yang dikembalikan oleh DdLock adalah beberapa pemetaan memori video. Pemetaan memori video ini dapat berupa pemetaan mode pengguna memori video nonlokal yang dilakukan oleh runtime mode kernel DirectDraw atau pemetaan yang disediakan oleh fungsi DdMapMemory driver. Jika penunjuk memori tidak dapat dikaitkan dengan salah satu pemetaan ini, runtime tidak memetakan ulang kunci. Sakelar mode berlanjut, yang berarti bahwa objek permukaan driver tidak terkunci dan dihancurkan melalui panggilan ke fungsi DdUnlock dan DdDestroySurface driver masing-masing. Driver kemudian biasanya melepaskan memori sistem apa pun yang dialokasikan driver pada waktu kunci. Karena aplikasi masih menulis ke memori ini, pelanggaran akses terjadi.

Akibatnya, driver tidak boleh mencoba mengembalikan penunjuk memori sistem dari fungsi DdLock-nya kecuali fungsi DdCreateSurface driver sebelumnya mengalokasikan memori tersebut dengan bendera PLEASE_ALLOC_USERMEM. Runtime DirectDraw memiliki memori yang dialokasikan dengan cara ini dan dapat menangguhkan rilis memori ini sampai aplikasi membuka kunci memori. Oleh karena itu, fungsi DdLock driver dapat mengembalikan pointer ke memori yang dialokasikan dengan cara ini tanpa risiko crash aplikasi.