Antarmuka ID2D1CommandList (d2d1_1.h)

Artikel
08/22/2023

Mewakili urutan perintah yang dapat direkam dan diputar kembali.

Warisan

Antarmuka ID2D1CommandList mewarisi dari ID2D1Image. ID2D1CommandList juga memiliki jenis anggota berikut:

Metode

Antarmuka ID2D1CommandList memiliki metode ini.


ID2D1CommandList::Close Menginstruksikan daftar perintah untuk berhenti menerima perintah sehingga Anda dapat menggunakannya sebagai input ke efek atau dalam panggilan ke ID2D1DeviceContext::D rawImage.
ID2D1CommandList::Stream Mengalirkan konten daftar perintah ke sink perintah yang ditentukan.

Keterangan

Daftar perintah tidak menyertakan salinan statis sumber daya dengan kumpulan perintah yang direkam. Semua bitmap, efek, dan geometri disimpan sebagai referensi ke sumber daya aktual dan semua kuas disimpan berdasarkan nilai. Semua pembuatan dan penghancuran sumber daya terjadi di luar daftar perintah. Tabel berikut ini mencantumkan sumber daya dan bagaimana mereka diperlakukan di dalam daftar perintah.

Sumber daya	Cara diperlakukan oleh daftar perintah
Kuas warna padat	Diteruskan oleh nilai.
Kuas bitmap	Kuas diteruskan oleh nilai tetapi bitmap yang digunakan untuk membuat kuas sebenarnya direferensikan.
Sikat gradien – gradien linier dan radial	Kuas diteruskan oleh nilai tetapi koleksi stop gradien itu sendiri direferensikan. Objek pengumpulan stop gradien tidak dapat diubah.
Bitmap	Diteruskan oleh referensi.
Blok status gambar	Status aktual pada konteks perangkat dikonversi menjadi fungsi yang ditetapkan seperti transformasi yang ditetapkan dan diteruskan oleh nilai.
Geometri	Objek yang tidak dapat diubah diteruskan oleh nilai.
Gaya goresan	Objek yang tidak dapat diubah diteruskan oleh nilai.
Jala	Objek yang tidak dapat diubah diteruskan oleh nilai.

Menggunakan CommandList sebagai Target

Pseudocode berikut mengilustrasikan kasus yang berbeda di mana target ditetapkan sebagai daftar perintah atau sebagai bitmap.

//create a D2D device from an already created DXGI device 
ID2D1Device *pD2D1Device;
pD2D1Factory->CreateDevice(pDxgiDevice, &amp;pD2D1Device);

//create a D2D device context from the D2D device
ID2D1DeviceContext *pD2D1DeviceContext;
pD2D1Device->CreateD2D1DeviceContext(&amp;pD2D1DeviceContext);

//create command list
ID2D1CommandList *pCommandList1;
pD2D1DeviceContext->CreateCommandList(&amp;pCommandList1);

//CreateBitmap
ID2D1Bitmap *pBitmap1;
ID2D1Bitmap *pBitmap2;
pD2D1DeviceContext->CreateBitmap(…, &amp;pBitmap1);
pD2D1DeviceContext->CreateBitmap(…, &amp;pBitmap2);

//Set the bitmap as the target
pD2D1DeviceContext->SetTarget(pBitmap1);
pD2D1DeviceContext->BeginDraw();
RenderMyVectorContent(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//Set the command list as the target
pD2D1DeviceContext->SetTarget(pCommandList1);
pD2D1DeviceContext->BeginDraw();
RenderMyVectorContent(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//Drawing a command list to a bitmap target
pD2D1DeviceContext->SetTarget(pBitmap2);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawImage(pCommandList1);
pD2D1DeviceContext->EndDraw();

Atur bitmap sebagai target:Dalam hal ini, semua konten yang dirender ke bitmap dirasterisasi. Jika bitmap ini digunakan di tempat lain, bitmap ini tidak akan beresolusi independen dan jika transformasi seperti Skala Kualitas Tinggi digunakan, bitmap ini tidak akan mempertahankan keakuratan.
Atur daftar perintah sebagai target:Dalam hal ini, alih-alih adegan yang dirasterisasi, semua perintah direkam. Ketika daftar perintah digunakan nanti untuk gambar layar menggunakan ID2D1DeviceContext::D rawImage atau diteruskan ke kontrol cetak XPS, konten vektor diputar ulang tanpa kehilangan keakuratan.
Menggambar daftar perintah ke target bitmap:Dalam hal ini karena target adalah bitmap, daftar perintah digambar ke bitmap dan tidak lagi beresolusi independen.

Satu-satunya cara untuk mempertahankan konten vektor untuk pemutaran nanti dengan keakuratan penuh adalah dengan mengatur jenis target sebagai daftar perintah. Ketika bitmap ditetapkan sebagai target, setiap gambar pada target tersebut akan dirasterisasi.

Menggunakan CommandList untuk Membuat Brush

Daftar perintah adalah cara yang baik untuk mendukung kuas pola, karena mereka mampu mempertahankan keakuratan pada pemutaran ulang. Pola yang diinginkan dapat disimpan sebagai daftar perintah, yang dapat digunakan untuk membuat kuas gambar. Kuas ini kemudian dapat digunakan untuk melukis jalur.

Jenis kuas yang mendukung pengisian jalur dengan daftar perintah disebut kuas gambar.

Psuedocode berikut mengilustrasikan proses penggunaan daftar perintah dengan kuas gambar.

//Draw the pattern to the command list
ID2D1CommandList *pCommandList;
pD2D1DeviceContext->SetTarget(pCommandList);
pD2D1DeviceContext->BeginDraw();
DrawMyPattern(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//Create the image brush from the command list
ID2D1ImageBrush *pImageBrush;
pD2D1DeviceContext->CreateImageBrush(
	pCommandList, 
	pImageBrushProperties,
	pBrushProperties,
	&amp;pImageBrush);

//Fill the ellipse with the pattern brush
pD2D1DeviceContext->SetTarget(pTargetBitmap);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->FillEllipse(pEllipse, pImageBrush);
pD2D1DeviceContext->EndDraw();

Karena kuas menerima gambar, ia juga memiliki manfaat lain berikut:

Karena output grafik efek adalah gambar, gambar ini dapat digunakan untuk membuat kuas gambar, yang secara efektif memberikan kemampuan menggunakan efek sebagai isian.
Karena daftar perintah adalah jenis gambar, konten vektor dapat dimasukkan ke dalam grafik efek dan juga dapat di petak atau dioperasikan. Misalnya, pemberitahuan hak cipta besar dapat dimasukkan melalui grafik dengan gambar virtual dan kemudian dikodekan.

Menggunakan CommandList sebagai Pengganti Target Render yang Kompatibel

Target render yang kompatibel sangat sering digunakan untuk penyajian di luar layar ke bitmap perantara yang kemudian disusun dengan adegan aktual. Terutama dalam kasus pencetakan, menggunakan target render yang kompatibel akan meningkatkan jejak memori karena semuanya akan dirasterisasi dan dikirim ke XPS alih-alih mempertahankan primitif aktual. Dalam skenario ini, pengembang lebih baik mengganti target render yang kompatibel dengan daftar perintah perantara. Kode pseudo berikut mengilustrasikan titik ini.

pD2D1Device->CreateDeviceContext(&amp;pD2D1DeviceContext);
pRenderTarget->CreateCompatibleRenderTarget(…, &amp;pCompatibleRenderTarget);

//render to the compatible render target
pCompatibleRenderTarget->BeginDraw();
RenderMyScene1(pCompatibleRenderTarget);
pCompatibleRenderTarget->EndDraw();

//get the bitmap from the compatible render target
pCompatibleRenderTarget->GetBitmap(pCompatBitmap);

//draw this bitmap on the device context
pD2D1DeviceContext->SetTarget(pTargetBitmap)
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawBitmap(pCompatBitmap);
pD2D1DeviceContext->EndDraw();

//draw something else on the compatible render target
pCompatibleRenderTarget->BeginDraw();
pCompatibleRenderTarget->Clear();
pCompatibleRenderTarget&gt;RenderScene2();
pCompatibleRenderTarget->EndDraw();

//get the bitmap from the compatible render target
pCompatibleRenderTarget->GetBitmap(pCompatBitmap);

//draw this bitmap on the device context
pD2D1DeviceContext->SetTarget(pTargetBitmap)
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawBitmap(pCompatBitmap);
pD2D1DeviceContext->EndDraw();


//Use a command list instead for better quality and performance 

//store the original target
pOriginalTarget = pD2D1DeviceContext->GetTarget();

pD2D1DeviceContext->CreateCommandList(pCommandList1);

//draw to command list 1
pD2D1DeviceContext->SetTarget(pCommandList1);
pD2D1DeviceContext->BeginDraw();
RenderMyScene1(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//draw the command list to the original target
pD2D1DeviceContext->SetTarget(pOriginalTarget);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawImage(pCommandList1);
pD2D1DeviceContext->EndDraw();

pD2D1DeviceContext->CreateCommandList(pCommandList2);

//draw something else to a new command list
pD2D1DeviceContext->SetTarget(pCommandList2);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->RenderScene2();
pD2D1DeviceContext->EndDraw();

//draw the new command list on the old command list
pD2D1DeviceContext->SetTarget(pCommandList1);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawImage(pCommandList2);
pD2D1DeviceContext->EndDraw();

Bekerja dengan API Lain

Direct2D menggunakan model sederhana saat beroperasi dengan API GDI dan Direct3D/DXGI. Daftar perintah tidak merekam perintah ini. Ini malah mem-rasterisasi konten di tempat dan menyimpannya sebagai ID2D1Bitmap. Karena isinya dirasterisasi, titik interop ini tidak mempertahankan keakuratan tinggi.

GDI: Antarmuka sink perintah tidak mendukung panggilan Get/ReleaseDC(). Saat panggilan ke ID2D1GdiInteropRenderTarget::ReleaseDC dilakukan, Direct2D merender konten wilayah yang diperbarui ke dalam D2D1Bitmap. Ini akan diputar ulang sebagai panggilan DrawBitmap alias dengan mode komposit salin. Untuk melakukan rasterisasi bitmap pada DPI yang benar, pada saat pemutaran perintah, nilai DPI apa pun yang diatur menggunakan fungsi SetDPI() digunakan. Ini adalah satu-satunya kasus di mana sink mematuhi panggilan SetDPI().

DX: Direct3D tidak dapat merender langsung ke daftar perintah. Untuk merender konten Direct3D dalam hal ini, aplikasi dapat memanggil DrawBitmap dengan ID2D1Bitmap yang didukung oleh permukaan Direct3D.

Persyaratan


Klien minimum yang didukung	Pembaruan Windows 8 dan Platform untuk Windows 7 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 dan Pembaruan Platform untuk Windows Server 2008 R2 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	d2d1_1.h