ID2D1DeviceContext::SetTarget-Methode (d2d1_1.h)

Die Bitmap oder Befehlsliste, in die der Direct2D-Gerätekontext nun gerendert wird.

Syntax

void SetTarget(
  [in, optional] ID2D1Image *image
);

Parameter

[in, optional] image

Typ: ID2D1Image*

Die Oberflächen- oder Befehlsliste, auf die der Direct2D-Gerätekontext gerendert wird.

Rückgabewert

Keine

Bemerkungen

Das Ziel kann jederzeit geändert werden, auch während der Kontext zeichnet.

Das Ziel kann entweder eine Bitmap sein, die mit dem flag D2D1_BITMAP_OPTIONS_TARGET erstellt wurde, oder es kann sich um eine Befehlsliste handeln. Andere Arten von Bildern können nicht als Ziel festgelegt werden. Beispielsweise können Sie die Ausgabe eines Effekts nicht als Ziel festlegen. Wenn das Ziel ungültig ist, wechselt der Kontext in den D2DERR_INVALID_TARGET Fehlerzustand.

Sie können SetTarget nicht verwenden, um aus mehreren Gerätekontexten gleichzeitig in einer Bitmap-/Befehlsliste zu rendern. Ein Bild wird als "in gerendert" betrachtet, wenn es jemals innerhalb eines BeginDraw/EndDraw-Zeitraums für einen Gerätekontext festgelegt wurde. Wenn versucht wird, ein Bild über mehrere Gerätekontexte zu rendern, werden alle nachfolgenden Gerätekontexte nach dem ersten in einen Fehlerzustand versetzt.

Aufrufer, die ein Bild an einen zweiten Gerätekontext anfügen möchten, sollten zuerst EndDraw für den ersten Gerätekontext aufrufen.

Hier sehen Sie ein Beispiel für die richtige Aufrufreihenfolge.

pDC1->BeginDraw();
pDC1->SetTarget(pImage);
// …
pDC1->EndDraw();

pDC2->BeginDraw();
pDC2->SetTarget(pImage);
// …
pDC2->EndDraw();

Hier sehen Sie ein Beispiel für die falsche Aufrufreihenfolge.

pDC1->BeginDraw();
pDC2->BeginDraw();

pDC1->SetTarget(pImage);

// ...

pDC1->SetTarget(NULL);

pDC2->SetTarget(pImage); // This call is invalid, even though pImage is no longer set on pDC1.

// ...

pDC1->EndDraw(); // This EndDraw SUCCEEDs.
pDC2->EndDraw(); // This EndDraw FAILs

Hinweis Durch das Ändern des Ziels wird weder die Bitmap geändert, aus der ein HWND-Renderziel angezeigt wird, noch die Bitmap, zu der ein DC-Renderziel führt.

 

Diese API erleichtert es einer Anwendung, eine Bitmap als Quelle (z. B. in DrawBitmap) und gleichzeitig als Ziel zu verwenden. Wenn Sie versuchen, eine Bitmap als Quelle auf demselben Gerätekontext zu verwenden, an den sie als Ziel gebunden ist, wird der Gerätekontext in den D2DERR_BITMAP_BOUND_AS_TARGET Fehlerzustand versetzt.

Es ist akzeptabel, eine Bitmap als Zielbitbit auf mehreren Renderzielen gleichzeitig zu binden. Anwendungen, die dies tun, müssen das Rendering ordnungsgemäß mit Flush oder EndDraw synchronisieren.

Sie können das Ziel jederzeit ändern, auch während der Kontext zeichnet.

Sie können das Ziel auf NULL festlegen. In diesem Fall versetzen Zeichnungsaufrufe den Gerätekontext mit D2DERR_WRONG_STATE in einen Fehlerzustand. Wenn Sie SetTarget mit einem NULL-Ziel aufrufen, wird die ursprüngliche Zielbit nicht im Gerätekontext wiederhergestellt.

Wenn der Gerätekontext über eine ausstehende HDC verfügt, wechselt der Kontext in den D2DERR_WRONG_STATE Fehlerzustand. Das Ziel wird nicht geändert.

Wenn sich die Bitmap und der Gerätekontext nicht in derselben Ressourcendomäne befinden, wechselt der Kontext in den \ Fehlerzustand. Das Ziel wird nicht geändert.

ID2D1RenderTarget::GetPixelSize gibt die Größe der aktuellen Zielbit zurück (oder 0, 0), wenn keine Bitmap gebunden ist). ID2D1RenderTarget::GetSize gibt die Pixelgröße der aktuellen Bitmap zurück, die um den DPI-Wert des Renderziels skaliert wird. SetTarget wirkt sich nicht auf den DPI-Wert des Renderziels aus.

ID2D1RenderTarget::GetPixelFormat gibt das Pixelformat der aktuellen Zielbit zurück (oder DXGI_FORMAT_UNKNOWN, D2D1_ALPHA_MODE_UNKNOWN, wenn keine vorhanden ist).

ID2D1Bitmap::CopyFromRenderTarget-Kopien aus der aktuell gebundenen Zielbitbitbit.

Anforderungen

Anforderung	Wert
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
DLL	D2d1.dll

Weitere Informationen

ID2D1Bitmap1

ID2D1DeviceContext

ID2D1DeviceContext::CreateBitmap

ID2D1DeviceContext::GetTarget