ID2D1CommandList-Schnittstelle (d2d1_1.h)

Artikel
08/22/2023

Stellt eine Sequenz von Befehlen dar, die aufgezeichnet und wiedergegeben werden können.

Vererbung

Die ID2D1CommandList-Schnittstelle erbt von ID2D1Image. ID2D1CommandList verfügt auch über folgende Membertypen:

Methoden

Die ID2D1CommandList-Schnittstelle verfügt über diese Methoden.


ID2D1CommandList::Close Weist die Befehlsliste an, die Annahme von Befehlen zu beenden, sodass Sie sie als Eingabe für einen Effekt oder in einem Aufruf von ID2D1DeviceContext::D rawImage verwenden können.
ID2D1CommandList::Stream Streamt den Inhalt der Befehlsliste an die angegebene Befehlssenke.

Hinweise

Die Befehlsliste enthält keine statischen Kopien von Ressourcen mit dem aufgezeichneten Befehlssatz. Alle Bitmaps, Effekte und Geometrien werden als Verweise auf die tatsächliche Ressource gespeichert, und alle Pinsel werden nach Wert gespeichert. Die gesamte Ressourcenerstellung und -zerstörung erfolgt außerhalb der Befehlsliste. In der folgenden Tabelle sind Ressourcen und deren Behandlung innerhalb einer Befehlsliste aufgeführt.

Resource	Behandlung durch die Befehlsliste
Volltonpinsel	Wird als Wert übergeben.
Bitmappinsel	Der Pinsel wird nach Wert übergeben, aber auf die Bitmap, die zum Erstellen des Pinsels verwendet wird, wird tatsächlich verwiesen.
Farbverlaufpinsel – sowohl linearer als auch radialer Farbverlauf	Der Pinsel wird als Wert übergeben, aber auf die Farbverlaufsstoppauflistung selbst wird verwiesen. Das Farbverlaufsstopp-Auflistungsobjekt ist unveränderlich.
Bitmaps	Wird als Verweis übergeben.
Zeichnungszustandsblock	Der tatsächliche Zustand im Gerätekontext wird in festgelegte Funktionen wie set transform konvertiert und nach Wert übergeben.
Geometrie	Unveränderliches Objekt, das als Wert übergeben wird.
Strichstil	Unveränderliches Objekt, das als Wert übergeben wird.
Mesh	Unveränderliches Objekt, das als Wert übergeben wird.

Verwenden einer CommandList als Ziel

Der folgende Pseudocode veranschaulicht die verschiedenen Fälle, in denen ein Ziel entweder als Befehlsliste oder als Bitmap festgelegt ist.

//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();

Legen Sie die Bitmap als Ziel fest:In diesem Fall werden alle Inhalte, die in der Bitmap gerendert werden, gerastert. Wenn diese Bitmap an anderer Stelle verwendet wird, ist sie nicht auflösungsunabhängig, und wenn eine Transformation wie high quality scale verwendet wird, wird die Genauigkeit nicht beibehalten.
Legen Sie die Befehlsliste als Ziel fest:In diesem Fall werden nicht die Szene gerastert, sondern alle Befehle aufgezeichnet. Wenn die Befehlsliste später mit ID2D1DeviceContext::D rawImage verwendet oder an ein XPS-Drucksteuerelement übergeben wird, wird der Vektorinhalt ohne Genauigkeitsverlust wiedergegeben.
Zeichnen einer Befehlsliste auf ein Bitmapziel:In diesem Fall, da das Ziel eine Bitmap ist, wird die Befehlsliste auf die Bitmap gezeichnet und ist nicht mehr auflösungsunabhängig.

Die einzige Möglichkeit, Vektorinhalte für die spätere Wiedergabe mit voller Genauigkeit beizubehalten, besteht darin, den Zieltyp als Befehlsliste festzulegen. Wenn eine Bitmap als Ziel festgelegt wird, wird jede Zeichnung auf diesem Ziel gerastert.

Verwenden einer CommandList zum Erstellen eines Pinsels

Befehlslisten sind eine gute Möglichkeit, Musterpinsel zu unterstützen, da sie die Wiedergabetreue beibehalten können. Das gewünschte Muster kann als Befehlsliste gespeichert werden, die zum Erstellen eines Bildpinsels verwendet werden kann. Dieser Pinsel kann dann zum Zeichnen von Pfaden verwendet werden.

Der Pinseltyp, der das Füllen eines Pfads mit einer Befehlsliste unterstützt, wird als Bildpinsel bezeichnet.

Der folgende psuedocode veranschaulicht den Prozess der Verwendung einer Befehlsliste mit einem Bildpinsel.

//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();

Da der Pinsel ein Bild akzeptiert, bietet er auch die folgenden weiteren Vorteile:

Da die Ausgabe eines Effektdiagramms ein Bild ist, kann dieses Bild verwendet werden, um einen Bildpinsel zu erstellen, der effektiv die Möglichkeit bietet, einen Effekt als Füllung zu verwenden.
Da es sich bei der Befehlsliste um einen Bildtyp handelt, können Vektorinhalte in ein Effektdiagramm eingefügt und auch gekachelt oder bearbeitet werden. Beispielsweise kann ein großer Copyrighthinweis über ein Diagramm mit einem virtualisierten Bild eingefügt und dann codiert werden.

Verwenden einer CommandList als Ersatz für ein kompatibles Renderziel

Kompatible Renderziele werden sehr häufig für das Rendern außerhalb des Bildschirms in einer zwischengeschalteten Bitmap verwendet, die später mit der tatsächlichen Szene zusammengesetzt wird. Insbesondere beim Drucken erhöht die Verwendung kompatibler Renderziele den Speicherbedarf, da alles gerastert und an XPS gesendet wird, anstatt die eigentlichen Grundtypen beizubehalten. In diesem Szenario ist es besser, das kompatible Renderziel durch eine zwischengeschaltete Befehlsliste zu ersetzen. Der folgende Pseudocode veranschaulicht diesen Punkt.

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();

Arbeiten mit anderen APIs

Direct2D verwendet bei der Zusammenarbeit mit GDI- und Direct3D/DXGI-APIs ein einfaches Modell. Die Befehlsliste zeichnet diese Befehle nicht auf. Stattdessen wird der Inhalt vor Ort gerastert und als ID2D1Bitmap gespeichert. Da der Inhalt gerastert ist, behalten diese Interoppunkte keine hohe Genauigkeit bei.

GDI: Die Befehlsenkenschnittstelle unterstützt keine Get/ReleaseDC()-Aufrufe. Wenn ein Aufruf von ID2D1GdiInteropRenderTarget::ReleaseDC erfolgt, rendert Direct2D den Inhalt der aktualisierten Region in eine D2D1Bitmap. Dies wird als Alias-DrawBitmap-Aufruf mit einem zusammengesetzten Kopiermodus wiedergegeben. Um die Bitmap mit dem richtigen DPI-Wert zu rastern, wird zum Zeitpunkt der Wiedergabe der Befehle jeder DPI-Wert verwendet, der mithilfe der SetDPI()-Funktion festgelegt wird. Dies ist der einzige Fall, in dem die Senke den SetDPI()-Aufruf respektiert.

DX: Direct3D kann nicht direkt in der Befehlsliste gerendert werden. Um Direct3D-Inhalte in diesem Fall zu rendern, kann die Anwendung DrawBitmap mit der ID2D1Bitmap aufrufen, die von einer Direct3D-Oberfläche unterstützt wird.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8 und Plattformupdate für Windows 7 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 und Plattformupdate für Windows Server 2008 R2 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	d2d1_1.h