IDCompositionSurface::BeginDraw method (dcomp.h)

Artikel
03/14/2023

Memulai menggambar pada objek permukaan Microsoft DirectComposition ini. Persegi panjang pembaruan harus berada dalam batas permukaan; jika tidak, metode ini gagal.

Sintaks

HRESULT BeginDraw(
  [in, optional] const RECT *updateRect,
  [in]           REFIID     iid,
  [out]          void       **updateObject,
  [out]          POINT      *updateOffset
);

Parameter

[in, optional] updateRect

Jenis: const RECT*

Persegi panjang yang akan diperbarui. Jika parameter ini NULL, seluruh bitmap diperbarui.

[in] iid

Jenis: REFIID

Pengidentifikasi antarmuka yang akan diambil.

[out] updateObject

Jenis: batal**

Menerima penunjuk antarmuka dari jenis yang ditentukan dalam parameter iid . Parameter ini tidak boleh NULL.

Catatan Dalam Windows 8, parameter ini adalah permukaan.

[out] updateOffset

Jenis: TITIK*

Offset ke permukaan tempat aplikasi harus menggambar konten yang diperbarui. Offset ini akan mereferensikan sudut kiri atas persegi panjang pembaruan.

Nilai kembali

Jenis: HRESULT

Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.

Keterangan

Metode ini memungkinkan aplikasi untuk memperbarui konten objek permukaan DirectComposition secara bertahap. Aplikasi harus menggunakan urutan berikut:

Panggil BeginDraw untuk memulai pembaruan inkremental.
Gunakan permukaan yang diambil sebagai target render dan gambar konten yang diperbarui pada offset yang diambil.
Panggil metode IDCompositionSurface::EndDraw untuk menyelesaikan pembaruan.

Objek pembaruan yang dikembalikan oleh metode ini adalah konteks perangkat Direct2D atau permukaan DXGI, tergantung pada nilai parameter iid dan tentang bagaimana objek permukaan DirectComposition dibuat. Jika parameter iid adalah __uuidof(ID2D1DeviceContext), maka objek yang dikembalikan adalah konteks perangkat Direct2D yang sudah memiliki permukaan DirectComposition yang dipilih sebagai target render. Jika tidak, ini adalah permukaan DXGI yang dapat digunakan aplikasi sebagai target render. Dalam kedua kasus, objek yang dikembalikan dikaitkan dengan perangkat Direct2D atau DXGI yang diteruskan oleh aplikasi ke fungsi DCompositionCreateDevice2 atau metode IDCompositionDevice2::CreateSurfaceFactory .

Parameter iid hanya dapat __uuidof(ID2D1DeviceContext) jika objek permukaan DirectComposition dibuat dari perangkat DirectComposition atau pabrik permukaan yang, dibuat dengan perangkat Direct2D terkait. Secara khusus, aplikasi harus memanggil fungsi DCompositionCreateDevice2 atau metode IDCompositionDevice2::CreateSurfaceFactory dengan perangkat Direct2D sebagai parameter renderingDevice . Jika permukaan DirectComposition dibuat melalui pabrik permukaan yang tidak terkait dengan perangkat Direct2D, atau jika dibuat langsung melalui antarmuka IDCompositionDevice2 dan perangkat tidak terkait langsung dengan perangkat Direct2D, maka meneruskan __uuidof (ID2D1DeviceContext) karena parameter iid menyebabkan metode ini mengembalikan E_INVALIDARG.

Jika aplikasi berhasil mengambil konteks perangkat Direct2D sebagai objek pembaruan, aplikasi tidak boleh memanggil metode ID2D1DeviceContext::BeginDraw atau ID2D1DeviceContext::EndDraw pada konteks perangkat Direct2D yang dikembalikan.

Offset yang diambil belum tentu sama dengan sudut kiri atas persegi panjang pembaruan yang diminta. Aplikasi harus mengubah primitif penyajiannya untuk menggambar dalam persegi panjang dengan lebar dan tinggi yang sama dengan persegi panjang input, tetapi pada offset yang diberikan. Aplikasi tidak boleh menggambar di luar persegi ini.

Jika parameter updateRectangle ADALAH NULL, seluruh permukaan diperbarui. Dalam hal ini, karena offset yang diambil masih mungkin bukan (0,0), aplikasi masih perlu mengubah primitif penyajiannya.

Jika permukaan bukan permukaan virtual, maka pertama kali aplikasi memanggil metode ini untuk permukaan non-virtual tertentu, persegi panjang pembaruan harus mencakup seluruh permukaan, baik dengan menentukan permukaan penuh dalam persegi pembaruan yang diminta, atau dengan menentukan NULL sebagai parameter updateRectangle . Untuk permukaan virtual, panggilan pertama mungkin merupakan sub-persegi panjang permukaan.

Karena setiap panggilan ke metode ini mungkin mengambil objek yang berbeda di permukaan updateObject , aplikasi tidak boleh menyimpan penunjuk permukaan yang diambil. Aplikasi harus merilis pointer yang diambil segera setelah selesai menggambar.

Persegi panjang permukaan yang diambil tidak berisi konten bitmap sebelumnya. Aplikasi harus memperbarui setiap piksel dalam persegi pembaruan, baik dengan terlebih dahulu menghapus target render, atau dengan mengeluarkan cukup primitif penyajian untuk sepenuhnya menutupi persegi pembaruan. Karena konten awal permukaan pembaruan tidak terdefinisi, gagal memperbarui setiap piksel menyebabkan perilaku yang tidak terdefinisi.

Hanya satu permukaan DirectComposition yang dapat diperbarui pada satu waktu. Aplikasi harus menangguhkan gambar pada satu permukaan sebelum memulai atau melanjutkan untuk menggambar di permukaan lain. Jika aplikasi memanggil BeginDraw dua kali, baik untuk permukaan yang sama atau untuk permukaan lain milik perangkat DirectComposition yang sama, tanpa panggilan intervensi ke IDCompositionSurface::EndDraw, panggilan kedua gagal. Jika aplikasi memanggil IDCompositionDevice2::Commit tanpa memanggil EndDraw, pembaruan tetap tertunda. Pembaruan berlaku hanya setelah aplikasi memanggil EndDraw dan kemudian memanggil metode IDCompositionDevice2::Commit .

Persyaratan

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

Lihat juga

IDCompositionSurface

IDCompositionSurface::EndDraw