Menangani Kesalahan

Fungsi Direct3D versi 10 yang diterapkan driver tampilan mode pengguna biasanya memiliki VOID untuk jenis parameter pengembalian. Pengecualian utama untuk aturan ini adalah fungsi jenis UkuranObjTypeCalcPrivate (misalnya, fungsi CalcPrivateResourceSize). Jenis fungsi ini mengembalikan jenis parameter SIZE_T yang menunjukkan ukuran wilayah memori yang diperlukan driver untuk membuat jenis objek tertentu melalui fungsi Buat jenis ObjType (misalnya, CreateResource(D3D10)).

Mengembalikan VOID mencegah driver tampilan mode pengguna memberi tahu runtime Direct3D tentang kesalahan dengan cara konvensional (yaitu, melalui parameter pengembalian fungsi driver tampilan mode pengguna). Sebagai gantinya, driver tampilan mode pengguna harus menggunakan fungsi panggilan balik pfnSetErrorCb runtime Direct3D untuk meneruskan informasi tersebut kembali ke runtime. Runtime memasok pointer ke pfnSetErrorCb dalam struktur D3D10DDI_CORELAYER_DEVICECALLBACKS yang ditunjukkan anggota struktur D3D10DDIARG_CREATEDEVICEpUMCallbacks dalam panggilan ke fungsi CreateDevice (D3D10).

Halaman referensi untuk setiap fungsi driver tampilan mode pengguna menentukan kesalahan yang dapat diteruskan fungsi melalui panggilan ke pfnSetErrorCb. Ini berarti bahwa jika driver tampilan mode pengguna memanggil pfnSetErrorCb dengan kode kesalahan yang tidak diizinkan untuk fungsi driver tampilan mode pengguna saat ini, runtime menentukan bahwa kondisi kesalahan sangat penting dan bertindak dengan tepat. Karena runtime akan bertindak dengan tepat selama pfnSetErrorCb, Anda seharusnya tidak mengharapkan bahwa Anda dapat membalikkan efek panggilan pfnSetErrorCb( E_FAIL ) dengan memanggil sesuatu seperti pfnSetErrorCb( S_OK ). Bahkan, runtime menentukan bahwa S_OK sama tidak valid atau kritis seperti E_FAIL. Konsep kode pengembalian S_OK setara dengan fungsi driver tampilan mode pengguna yang tidak memanggil pfnSetErrorCb sama sekali.

Jika runtime Direct3D menentukan bahwa kondisi kesalahan sangat penting, pertama-tama akan mengambil tindakan dengan mencatat kesalahan dengan Dr. Watson--debugger post-mortem default (just-in-time). Runtime kemudian akan kehilangan perangkat dengan sengaja, sehingga meniru skenario penerimaan kode kesalahan D3DDDIERR_DEVICEREMOVED. Dengan mengharuskan driver untuk memanggil fungsi panggilan balik pfnSetErrorCb , kemungkinan jauh lebih besar bahwa setiap kesalahan yang keluar dari driver akan memiliki tumpukan panggilan yang berguna yang terkait dengannya. Memiliki tumpukan panggilan yang terkait dengan kesalahan memungkinkan diagnosis cepat dan log Dr. Watson yang akurat.

Anda harus menggunakan pfnSetErrorCb dalam kode driver Anda ketika ada yang salah di driver Anda meskipun mengembalikan kode kesalahan yang tidak memungkinkan runtime untuk fungsi driver tertentu ditentukan oleh runtime sebagai bug atau masalah driver. Akan lebih buruk lagi bagi driver tampilan mode pengguna untuk menyerap kesalahan kritis dan melanjutkan. Driver tampilan mode pengguna harus memanggil pfnSetErrorCb sedekat mungkin dengan titik deteksi kesalahan untuk menyediakan tumpukan panggilan yang berguna untuk penelusuran kesalahan pasca-mortem.

Tabel berikut mencantumkan kategori kesalahan yang diizinkan runtime Direct3D dari fungsi driver tertentu.

Kategori kesalahan	Makna
NoErrors	Driver seharusnya tidak mengalami kesalahan apa pun, termasuk D3DDDIERR_DEVICEREMOVED. Runtime akan menentukan bahwa panggilan apa pun ke pfnSetErrorCb sangat penting.
AllowDeviceRemoved	Driver seharusnya tidak mengalami kesalahan apa pun, kecuali untuk D3DDDIERR_DEVICEREMOVED. Runtime akan menentukan bahwa setiap panggilan ke pfnSetErrorCb yang tidak lulus D3DDDIERR_DEVICEREMOVED sangat penting. Driver tidak diperlukan untuk mengembalikan DEVICEREMOVED jika perangkat telah dihapus. Namun, runtime memungkinkan driver untuk mengembalikan DEVICEREMOVED, jika DEVICEREMOVED mengganggu fungsi driver, yang biasanya tidak boleh terjadi.
AllowOutOfMemory	Driver mungkin kehabisan memori. Oleh karena itu, driver dapat melewati E_OUTOFMEMORY dan D3DDDIERR_DEVICEREMOVED melalui pfnSetErrorCb. Runtime akan menentukan bahwa kode kesalahan lainnya sangat penting.
AllowCounterCreationErrors	Driver mungkin kehabisan memori. Driver juga mungkin tidak dapat membuat penghitung karena sifat eksklusif penghitung. Oleh karena itu, driver dapat melewati E_OUTOFMEMORY, DXGI_DDI_ERR_NONEXCLUSIVE, dan D3DDDIERR_DEVICEREMOVED melalui pfnSetErrorCb. Runtime akan menentukan bahwa kode kesalahan lainnya sangat penting.
AllowMapErrors	Driver harus memeriksa ketidakcocokan sumber daya. Oleh karena itu, driver dapat melewati DXGI_DDI_ERR_WASSTILLDRAWING melalui pfnSetErrorCb jika bendera D3D10_DDI_MAP_FLAG_DONOTWAIT diteruskan ke fungsi ResourceMap driver. Driver juga dapat melewati D3DDDIERR_DEVICEREMOVED melalui pfnSetErrorCb. Runtime akan menentukan bahwa kode kesalahan lainnya sangat penting.
AllowGetDataErrors	Driver harus memeriksa penyelesaian kueri. Oleh karena itu, driver dapat melewati DXGI_DDI_ERR_WASSTILLDRAWING melalui pfnSetErrorCb jika kueri belum selesai. Driver juga dapat melewati D3DDDIERR_DEVICEREMOVED melalui pfnSetErrorCb. Runtime akan menentukan bahwa kode kesalahan lainnya sangat penting.
AllowWKCheckCounterErrors	Fungsi CheckCounter driver harus menunjukkan apakah mendukung penghitung yang ditentukan runtime. Oleh karena itu, driver dapat melewati DXGI_DDI_ERR_UNSUPPORTED melalui pfnSetErrorCb. Runtime akan menentukan bahwa kode kesalahan lainnya sangat penting. Driver tidak dapat mengembalikan D3DDDIERR_DEVICEREMOVED untuk fungsi check-type apa pun.
AllowDDCheckCounterErrors	Driver harus memvalidasi pengidentifikasi penghitung yang bergantung pada perangkat (ID penghitung) untuk memastikan bahwa ID penghitung berada dalam rentang dan ada cukup ruang untuk menyalin setiap string penghitung ke dalam buffer yang disediakan. Driver dapat melewati E_INVALIDARG melalui pfnSetErrorCb, ketika parameter salah dengan cara ini. Driver tidak dapat mengembalikan D3DDDIERR_DEVICEREMOVED untuk fungsi check-type apa pun.