Fungsi SetDisplayConfig (winuser.h)

Artikel
08/28/2023

Fungsi SetDisplayConfig memodifikasi mode topologi tampilan, sumber, dan target dengan mengaktifkan jalur yang ditentukan secara eksklusif dalam sesi saat ini.

Sintaks

LONG SetDisplayConfig(
  [in]           UINT32                  numPathArrayElements,
  [in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
  [in]           UINT32                  numModeInfoArrayElements,
  [in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
  [in]           UINT32                  flags
);

Parameter

[in] numPathArrayElements

Jumlah elemen dalam pathArray.

[in, optional] pathArray

Array dari semua jalur tampilan yang akan diatur. Hanya jalur dalam array ini yang memiliki bendera DISPLAYCONFIG_PATH_ACTIVE yang diatur dalam anggota benderaDISPLAYCONFIG_PATH_INFO yang diatur. Parameter ini bisa NULL. Urutan di mana jalur aktif muncul dalam array ini menentukan prioritas jalur. Untuk informasi selengkapnya tentang urutan prioritas jalur, lihat Urutan Prioritas Jalur.

[in] numModeInfoArrayElements

Jumlah elemen dalam modeInfoArray.

[in, optional] modeInfoArray

Array informasi mode sumber tampilan dan target (DISPLAYCONFIG_MODE_INFO) yang direferensikan oleh anggota modeInfoIdx dari DISPLAYCONFIG_PATH_SOURCE_INFO dan elemen DISPLAYCONFIG_PATH_TARGET_INFO informasi jalur dari pathArray. Parameter ini bisa NULL.

[in] flags

Bitwise ATAU nilai bendera yang menunjukkan perilaku fungsi ini. Parameter ini bisa menjadi salah satu nilai berikut, atau kombinasi nilai berikut; 0 tidak valid. Lihat di bawah ini untuk deskripsi kombinasi bendera yang valid.

Nilai	Makna
SDC_APPLY 0x00000080	Mode topologi, sumber, dan target yang dihasilkan diatur.
SDC_NO_OPTIMIZATION 0x00000100	Pengubah ke bendera SDC_APPLY. Hal ini menyebabkan mode perubahan dipaksa hingga ke driver untuk setiap tampilan aktif.
SDC_USE_SUPPLIED_DISPLAY_CONFIG 0x00000020	Informasi mode topologi, sumber, dan target yang disediakan dalam parameter pathArray dan modeInfoArray digunakan, daripada mencari konfigurasi dalam database.
SDC_SAVE_TO_DATABASE 0x00000200	Mode topologi, sumber, dan target yang dihasilkan disimpan ke database.
SDC_VALIDATE 0x00000040	Sistem menguji informasi topologi, sumber, dan mode target yang diminta untuk menentukan apakah dapat diatur.
SDC_ALLOW_CHANGES 0x00000400	Jika diperlukan, fungsi dapat memodifikasi informasi mode sumber dan target yang ditentukan untuk membuat set jalur tampilan fungsi.
SDC_TOPOLOGY_CLONE 0x00000002	Pemanggil meminta konfigurasi kloning terakhir dari database persistensi.
SDC_TOPOLOGY_EXTEND 0x00000004	Pemanggil meminta konfigurasi terakhir yang diperluas dari database persistensi.
SDC_TOPOLOGY_INTERNAL 0x00000001	Pemanggil meminta konfigurasi internal terakhir dari database persistensi.
SDC_TOPOLOGY_EXTERNAL 0x00000008	Pemanggil meminta konfigurasi eksternal terakhir dari database persistensi.
SDC_TOPOLOGY_SUPPLIED 0x00000010	Pemanggil menyediakan data jalur sehingga fungsi hanya mengkueri database persistensi untuk menemukan dan menggunakan mode sumber dan target.
SDC_USE_DATABASE_CURRENT (SDC_TOPOLOGY_INTERNAL \| SDC_TOPOLOGY_CLONE \| SDC_TOPOLOGY_EXTEND \| SDC_TOPOLOGY_EXTERNAL)	Pemanggil meminta kombinasi keempat konfigurasi SDC_TOPOLOGY_XXX. Nilai ini menginformasikan API untuk mengatur konfigurasi tampilan terakhir yang diketahui untuk monitor yang terhubung saat ini.
SDC_PATH_PERSIST_IF_REQUIRED 0x00000800	Ketika fungsi memproses permintaan SDC_TOPOLOGY_XXX, fungsi dapat memaksa persistensi jalur pada target untuk memenuhi permintaan jika perlu. Untuk informasi tentang bendera lain yang dapat digabungkan dengan bendera ini, lihat daftar berikut ini.
SDC_FORCE_MODE_ENUMERATION 0x00001000	Pemanggil meminta agar driver diberi kesempatan untuk memperbarui daftar mode GDI sementara SetDisplayConfig mengatur konfigurasi tampilan baru. Nilai bendera ini hanya valid ketika nilai bendera SDC_USE_SUPPLIED_DISPLAY_CONFIG dan SDC_APPLY juga ditentukan.
SDC_ALLOW_PATH_ORDER_CHANGES 0x00002000	Pengubah pada bendera SDC_TOPOLOGY_SUPPLIED yang menunjukkan bahwa SetDisplayConfig harus mengabaikan urutan jalur topologi yang disediakan saat mencari database. Ketika bendera ini diatur, set topologi adalah topologi terbaru yang berisi semua jalur terlepas dari urutan jalur.
SDC_VIRTUAL_MODE_AWARE 0x00008000	Pengubah pada bendera SDC_USE_SUPPLIED_DISPLAY_CONFIG dan SDC_TOPOLOGY_SUPPLIED yang diketahui pemanggil mode virtual. Didukung mulai dari Windows 10.
SDC_VIRTUAL_REFRESH_RATE_AWARE 0x00020000	Pengubah pada bendera SDC_USE_SUPPLIED_DISPLAY_CONFIG dan SDC_TOPOLOGY_SUPPLIED yang diketahui pemanggil tentang laju refresh virtual. Didukung mulai dari Windows 11.

Daftar berikut berisi kombinasi nilai yang valid untuk parameter Bendera :

Baik SDC_APPLY atau SDC_VALIDATE harus diatur, tetapi tidak keduanya.
Baik SDC_USE_SUPPLIED_DISPLAY_CONFIG atau kombinasi SDC_TOPOLOGY_XXX harus diatur. SDC_USE_SUPPLIED_DISPLAY_CONFIG tidak dapat diatur dengan bendera SDC_TOPOLOGY_XXX apa pun.
SDC_NO_OPTIMIZATION hanya dapat diatur dengan SDC_APPLY.
SDC_ALLOW_CHANGES diperbolehkan dengan kombinasi lain yang valid.
SDC_SAVE_TO_DATABASE hanya dapat diatur dengan SDC_USE_SUPPLIED_DISPLAY_CONFIG.
SDC_PATH_PERSIST_IF_REQUIRED tidak dapat digunakan dengan SDC_USE_SUPPLIED_DISPLAY_CONFIG atau SDC_TOPOLOGY_SUPPLIED.
SDC_FORCE_MODE_ENUMERATION hanya valid saat SDC_APPLY dan SDC_USE_SUPPLIED_DISPLAY_CONFIG ditentukan.
SDC_ALLOW_PATH_ORDER_CHANGES hanya diperbolehkan saat SDC_TOPOLOGY_SUPPLIED ditentukan.
SDC_TOPOLOGY_SUPPLIED tidak dapat digunakan dengan bendera SDC_TOPOLOGY_XXX lainnya. Karena masalah validasi, jika penelepon melanggar aturan ini, SetDisplayConfig tidak gagal. Namun, SetDisplayConfig mengabaikan bendera SDC_TOPOLOGY_SUPPLIED.

bendera SDC_TOPOLOGY_XXX dapat digunakan dalam kombinasi. Misalnya, jika SDC_TOPOLOGY_CLONE dan SDC_TOPOLOGY_EXTEND diatur, API menggunakan kloning terbaru atau memperluas topologi, yang setiap topologinya diatur dengan yang terbaru untuk monitor yang terhubung saat ini.

Nilai kembali

Fungsi mengembalikan salah satu kode pengembalian berikut.

Menampilkan kode	Deskripsi
ERROR_SUCCESS	Fungsi berhasil.
ERROR_INVALID_PARAMETER	Kombinasi parameter dan bendera yang ditentukan tidak valid.
ERROR_NOT_SUPPORTED	Sistem tidak menjalankan pengandar grafis yang ditulis sesuai dengan Windows Display Driver Model (WDDM). Fungsi ini hanya didukung pada sistem dengan driver WDDM berjalan.
ERROR_ACCESS_DENIED	Pemanggil tidak memiliki akses ke sesi konsol. Kesalahan ini terjadi jika proses panggilan tidak memiliki akses ke desktop saat ini atau sedang berjalan pada sesi jarak jauh.
ERROR_GEN_FAILURE	Terjadi kesalahan yang tidak ditentukan.
ERROR_BAD_CONFIGURATION	Fungsi tidak dapat menemukan solusi yang dapat dikerjakan untuk mode sumber dan target yang tidak ditentukan pemanggil.

Keterangan

Fungsi SetDisplayConfig mengambil jalur tampilan aktif dengan informasi mode sumber dan target yang ditentukan dan menggunakan logika mode terbaik untuk menghasilkan informasi mode sumber dan target yang hilang. Fungsi ini kemudian mengatur jalur tampilan lengkap.

Anggota ModeInfoIdx dalam struktur DISPLAYCONFIG_PATH_SOURCE_INFO dan DISPLAYCONFIG_PATH_TARGET_INFO digunakan untuk menunjukkan apakah mode sumber dan target disediakan untuk jalur aktif tertentu. Jika nilai indeks DISPLAYCONFIG_PATH_MODE_IDX_INVALID untuk keduanya, ini menunjukkan informasi mode tidak ditentukan. Ini berlaku untuk jalur ditambah mode sumber atau jalur ditambah informasi mode sumber dan target yang akan ditentukan untuk jalur tertentu. Namun, tidak valid untuk jalur ditambah mode target yang akan ditentukan tanpa mode sumber.

Mode sumber dan target untuk setiap pengidentifikasi sumber dan target hanya dapat muncul di array modeInfoArray sekali. Misalnya, mode sumber untuk pengidentifikasi sumber S1 hanya dapat muncul dalam tabel sekali; jika beberapa jalur mereferensikan sumber yang sama, mereka harus menggunakan ModeInfoIdx yang sama.

Harapannya adalah bahwa sebagian besar penelepon menggunakan QueryDisplayConfig untuk mendapatkan konfigurasi saat ini bersama dengan kemungkinan valid lainnya dan kemudian menggunakan SetDisplayConfig untuk menguji dan mengatur konfigurasi.

Urutan di mana jalur aktif muncul di array PathArray menentukan prioritas jalur.

Secara default, SetDisplayConfig tidak pernah mengubah jalur yang disediakan, mode sumber, atau informasi mode target. Jika logika mode terbaik tidak dapat menemukan solusi tanpa mengubah informasi jalur tampilan yang ditentukan, SetDisplayConfig gagal dengan ERROR_BAD_CONFIGURATION. Dalam hal ini, penelepon harus menentukan bendera SDC_ALLOW_CHANGES untuk memungkinkan fungsi mengubah beberapa detail sumber dan mode yang ditentukan untuk memungkinkan perubahan jalur tampilan berhasil.

Jika mode sumber dan target yang ditentukan atau dihitung memiliki dimensi yang sama, SetDisplayConfig secara otomatis mengatur penskalakan jalur ke DISPLAYCONFIG_PPR_IDENTITY sebelum mengatur jalur tampilan dan menyimpannya di database. Untuk informasi tentang cara SetDisplayConfig menangani penskalaan, lihat Menskalakan Gambar Desktop.

Ketika pemanggil menentukan bendera SDC_USE_SUPPLIED_DISPLAY_CONFIG untuk mengatur jalur kloning dan jika ada indeks mode sumber yang tidak valid dalam array jalur, SetDisplayConfig menentukan bahwa semua indeks mode sumber dari sumber tersebut tidak valid. SetDisplayConfig menggunakan logika mode terbaik untuk menentukan informasi mode sumber.

Kecuali untuk bendera SDC_TOPOLOGY_SUPPLIED (untuk informasi selengkapnya tentang SDC_TOPOLOGY_SUPPLIED, lihat paragraf berikut), bendera SDC_TOPOLOGY_XXX mengatur pengaturan jalur tampilan terakhir, termasuk informasi mode sumber dan target untuk jenis topologi tersebut. Untuk informasi tentang kombinasi bendera SDC_TOPOLOGY_XXX yang valid, lihat deskripsi parameter Bendera . Parameter pathArray dan modeInfoArray harus NULL, dan ukuran terkaitnya harus nol. Misalnya, jika SDC_TOPOLOGY_CLONE dan SDC_TOPOLOGY_EXTEND diatur, fungsi ini menggunakan kloning terbaru atau memperluas konfigurasi jalur tampilan. Jika satu jenis topologi diminta, konfigurasi terakhir dari jenis tersebut digunakan. Jika topologi tersebut belum pernah diatur sebelumnya, SetDisplayConfig menggunakan logika topologi terbaik untuk menemukan topologi terbaik, lalu logika mode terbaik untuk menemukan mode sumber dan target terbaik untuk digunakan. Jika kombinasi bendera topologi telah ditetapkan dan tidak ada yang memiliki entri database, prioritas berikut digunakan. Untuk laptop: kloning, perluas, internal, dan kemudian eksternal; untuk desktop, prioritas diperluas lalu kloning.

Pemanggil dapat menentukan bendera SDC_TOPOLOGY_SUPPLIED untuk menunjukkan bahwa ia hanya mengatur informasi jalur (topologi) dan permintaan yang diperoleh SetDisplayConfig lalu menggunakan informasi mode sumber dan target dari database persistensi. Jika jalur aktif yang disediakan pemanggil tidak memiliki entri dalam database persistensi, SetDisplayConfig gagal. Dalam hal ini, jika pemanggil memanggil SetDisplayConfig lagi dengan data jalur yang sama tetapi dengan set bendera SDC_USE_SUPPLIED_DISPLAY_CONFIG, SetDisplayConfig menggunakan logika mode terbaik untuk membuat informasi mode sumber dan target. Ketika pemanggil menentukan SDC_TOPOLOGY_SUPPLIED, pemanggil harus mengatur parameter numModeInfoArrayElements ke nol dan parameter modeInfoArray ke NULL; namun, pemanggil harus mengatur parameter pathArray dan numPathArrayElements untuk informasi jalur yang diperlukan pemanggil. Pemanggil harus menandai semua indeks mode sumber dan target sebagai tidak valid (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) dalam data jalur ini.

Tabel berikut ini menyediakan beberapa skenario umum di mana SetDisplayConfig dipanggil bersama dengan kombinasi bendera yang diteruskan pemanggil ke parameter Bendera untuk mencapai skenario.

Skenario	Kombinasi bendera
Menguji apakah konfigurasi tampilan yang ditentukan didukung pada komputer	SDC_VALIDATE \| SDC_USE_SUPPLIED_DISPLAY_CONFIG
Mengatur konfigurasi tampilan yang ditentukan dan menyimpan ke database	SDC_APPLY \| SDC_USE_SUPPLIED_DISPLAY_CONFIG \| SDC_SAVE_TO_DATABASE
Mengatur konfigurasi tampilan sementara (yaitu, konfigurasi tampilan tidak akan disimpan)	SDC_APPLY \| SDC_USE_SUPPLIED_DISPLAY_CONFIG
Menguji apakah kloning didukung di komputer	SDC_VALIDATE \| SDC_TOPOLOGY_CLONE
Mengatur topologi kloning	SDC_APPLY \| SDC_TOPOLOGY_CLONE
Atur topologi kloning dan izinkan persistensi jalur diaktifkan jika diperlukan untuk memenuhi permintaan	SDC_APPLY \| SDC_TOPOLOGY_CLONE \| SDC_PATH_PERSIST_IF_REQUIRED
Kembali dari mode sementara ke konfigurasi tampilan terakhir yang disimpan	SDC_APPLY\| SDC_USE_DATABASE_CURRENT
Hanya diberikan informasi jalur, atur konfigurasi tampilan dengan informasi sumber dan target dari database untuk jalur dan abaikan urutan jalur	SDC_APPLY \| SDC_TOPOLOGY_SUPPLIED \| SDC_ALLOW_PATH_ORDER_CHANGES

Virtualisasi DPI

API ini tidak berpartisipasi dalam virtualisasi DPI. Semua ukuran dalam struktur DEVMODE berada dalam hal piksel fisik, dan tidak terkait dengan konteks panggilan.

Persyaratan


Klien minimum yang didukung	Tersedia di Windows 7 dan versi yang lebih baru dari sistem operasi Windows.
Target Platform	Universal
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (diperkenalkan dalam Windows 10, versi 10.0.14393)