IDCompositionVisual::AddVisual method (dcomp.h)

Artikel
08/23/2023

Menambahkan visual anak baru ke daftar anak dari visual ini.

Sintaks

HRESULT AddVisual(
  [in]           IDCompositionVisual *visual,
  [in]           BOOL                insertAbove,
  [in, optional] IDCompositionVisual *referenceVisual
);

Parameter

[in] visual

Jenis: IDCompositionVisual*

Visual anak yang akan ditambahkan. Parameter ini tidak boleh NULL.

[in] insertAbove

Jenis: BOOL

TRUE untuk menempatkan visual anak baru di depan visual yang ditentukan oleh parameter referenceVisual , atau FALSE untuk menempatkannya di belakang referensiVisual.

[in, optional] referenceVisual

Jenis: IDCompositionVisual*

Visual anak yang ada di samping visual baru harus ditambahkan.

Mengembalikan nilai

Jenis: HRESULT

Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan. Lihat Kode Kesalahan DirectComposition untuk daftar kode kesalahan.

Keterangan

Visual anak disusun dalam daftar berurutan. Isi visual anak digambar di depan (atau di atas) isi visual induknya, tetapi di belakang (atau di bawah) isi turunannya.

Parameter referenceVisual harus merupakan anak yang ada dari visual induk, atau harus NULL. Parameter insertAbove menunjukkan apakah anak baru harus dirender tepat di atas visual referensi dalam urutan Z, atau tepat di bawahnya.

Jika parameter referenceVisual adalah NULL, visual yang ditentukan dirender di atas atau di bawah semua turunan visual induk, tergantung pada nilai parameter insertAbove . Jika insertAbove TRUE, visual anak baru di atas tanpa saudara kandung, oleh karena itu dirender di bawah semua saudara kandungnya. Sebaliknya, jika insertAbove FALSE, visual di bawah ini tidak ada saudara kandung, oleh karena itu dirender di atas semua saudara kandungnya.

Visual yang ditentukan oleh parameter visual tidak dapat berupa anak dari satu visual lainnya, atau akar pohon visual yang terkait dengan target komposisi. Jika visual sudah menjadi anak dari visual lain, AddVisual gagal. Visual anak harus dihapus dari daftar anak dari induk sebelumnya sebelum menambahkannya ke daftar turunan induk baru. Jika visual adalah akar pohon visual, visual harus dipisahkan dari pohon visual tersebut sebelum menambahkannya ke daftar turunan induk baru. Untuk memisahkan visual dari pohon visual, panggil metode IDCompositionTarget::SetRoot dan tentukan visual atau NULL yang berbeda sebagai parameter visual .

Visual anak tidak perlu dibuat oleh antarmuka IDCompositionDevice yang sama dengan induknya. Ketika visual dari perangkat yang berbeda digabungkan di pohon visual yang sama, Microsoft DirectComposition menyusun pohon seperti biasanya, kecuali bahwa perubahan pada visual tertentu hanya berlaku ketika IDCompositionDevice::Commit dipanggil pada objek perangkat yang membuat visual. Kemampuan untuk menggabungkan visual dari perangkat yang berbeda memungkinkan beberapa utas untuk membuat dan memanipulasi satu pohon visual sambil mempertahankan perangkat independen yang dapat digunakan untuk menerapkan perubahan secara asinkron

Metode ini gagal jika visual atau referensiVisual adalah penunjuk yang tidak valid, atau jika visual yang dirujuk oleh referensi Parameter virtual bukan anak dari visual induk. Antarmuka ini tidak dapat menjadi implementasi kustom; hanya antarmuka yang dibuat oleh DirectComposition yang dapat digunakan dengan metode ini.

Contoh

Misalnya, lihat Cara Membangun Pohon Visual Sederhana.

Persyaratan


Klien minimum yang didukung	Windows 8 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Target Platform	Windows
Header	dcomp.h
Pustaka	Dcomp.lib
DLL	Dcomp.dll