Freigeben über


IDCompositionSurface::BeginDraw-Methode (dcomp.h)

Initiiert das Zeichnen für dieses Microsoft DirectComposition-Oberflächenobjekt. Das Updaterechteck muss sich innerhalb der Grenzen der Oberfläche befinden. Andernfalls schlägt diese Methode fehl.

Syntax

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

Parameter

[in, optional] updateRect

Typ: const RECT*

Das zu aktualisierende Rechteck. Wenn dieser Parameter NULL ist, wird die gesamte Bitmap aktualisiert.

[in] iid

Typ: REFIID

Der Bezeichner der abzurufenden Schnittstelle.

[out] updateObject

Typ: void**

Empfängt einen Schnittstellenzeiger des im iid-Parameter angegebenen Typs . Dieser Parameter darf nicht NULL sein.

Hinweis In Windows 8 war dieser Parameter surface.
 

[out] updateOffset

Typ: POINT*

Der Offset in die Oberfläche, auf der die Anwendung aktualisierte Inhalte zeichnen soll. Dieser Offset verweist auf die obere linke Ecke des Updaterechtecks.

Rückgabewert

Typ: HRESULT

Wenn die Funktion erfolgreich ist, gibt sie S_OK zurück. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Mit dieser Methode kann eine Anwendung den Inhalt eines DirectComposition-Oberflächenobjekts inkrementell aktualisieren. Die Anwendung muss die folgende Sequenz verwenden:

  1. Rufen Sie BeginDraw auf, um das inkrementelle Update zu initiieren.
  2. Verwenden Sie die abgerufene Oberfläche als Renderziel, und zeichnen Sie die aktualisierten Inhalte am abgerufenen Offset.
  3. Rufen Sie die IDCompositionSurface::EndDraw-Methode auf, um das Update abzuschließen.
Das von dieser Methode zurückgegebene Updateobjekt ist entweder ein Direct2D-Gerätekontext oder eine DXGI-Oberfläche, abhängig vom Wert des iid-Parameters und der Erstellung des DirectComposition-Oberflächenobjekts. Wenn der iid-Parameter __uuidof(ID2D1DeviceContext) ist, ist das zurückgegebene Objekt ein Direct2D-Gerätekontext, in dem bereits die DirectComposition-Oberfläche als Renderziel ausgewählt ist. Andernfalls handelt es sich um eine DXGI-Oberfläche, die die Anwendung als Renderziel verwenden kann. In beiden Fällen wird das zurückgegebene Objekt dem Direct2D- oder DXGI-Gerät zugeordnet, das von der Anwendung an die DCompositionCreateDevice2-Funktion oder die IDCompositionDevice2::CreateSurfaceFactory-Methode übergeben wird.

Der iid-Parameter darf nur __uuidof(ID2D1DeviceContext) sein, wenn das DirectComposition-Surface-Objekt von einem DirectComposition-Gerät oder einer Surface Factory erstellt wurde, das selbst mit einem zugeordneten Direct2D-Gerät erstellt wurde. Insbesondere muss die Anwendung entweder die DCompositionCreateDevice2-Funktion oder die IDCompositionDevice2::CreateSurfaceFactory-Methode mit einem Direct2D-Gerät als renderingDevice-Parameter aufgerufen haben. Wenn die DirectComposition-Oberfläche über eine Surface Factory erstellt wurde, die nicht einem Direct2D-Gerät zugeordnet war, oder wenn sie direkt über die IDCompositionDevice2-Schnittstelle erstellt wurde und das Gerät nicht direkt einem Direct2D-Gerät zugeordnet war, übergeben Sie __uuidof(ID2D1DeviceContext), als der iid-Parameter bewirkt, dass diese Methode E_INVALIDARG zurückgibt.

Wenn die Anwendung erfolgreich einen Direct2D-Gerätekontext als Updateobjekt abruft, sollte die Anwendung weder die Methoden ID2D1DeviceContext::BeginDraw noch ID2D1DeviceContext::EndDraw für den zurückgegebenen Direct2D-Gerätekontext aufrufen.

Der abgerufene Offset ist nicht unbedingt mit der linken oberen Ecke des angeforderten Updaterechtecks identisch. Die Anwendung muss ihre Renderinggrundsätze transformieren, um innerhalb eines Rechtecks mit der gleichen Breite und Höhe wie das Eingaberechteck zu zeichnen, jedoch am angegebenen Offset. Die Anwendung sollte nicht außerhalb dieses Rechtecks zeichnen.

Wenn der parameter updateRectangle NULL ist, wird die gesamte Oberfläche aktualisiert. In diesem Fall muss die Anwendung ihre Renderinggrundsätze dennoch entsprechend transformieren, da der abgerufene Offset immer noch nicht (0,0) ist.

Wenn es sich bei der Oberfläche nicht um eine virtuelle Oberfläche handelt, muss das Updaterechteck beim ersten Aufruf dieser Methode für eine bestimmte nicht virtuelle Oberfläche die gesamte Oberfläche abdecken, entweder durch Angeben der vollständigen Oberfläche im angeforderten Updaterechteck oder durch Angeben von NULL als updateRectangle-Parameter . Bei virtuellen Oberflächen kann der erste Aufruf ein beliebiges Unterrechteck der Oberfläche sein.

Da jeder Aufruf dieser Methode möglicherweise ein anderes Objekt auf der updateObject-Oberfläche abruft , sollte die Anwendung den abgerufenen Oberflächenzeiger nicht zwischenspeichern. Die Anwendung sollte den abgerufenen Zeiger freigeben, sobald die Zeichnung abgeschlossen ist.

Das abgerufene Flächenrechteck enthält nicht den vorherigen Inhalt der Bitmap. Die Anwendung muss jedes Pixel im Updaterechteck aktualisieren, indem entweder zuerst das Renderziel entfernt wird oder genügend Renderinggrundsätze ausgegeben werden, um das Updaterechteck vollständig abzudecken. Da der anfängliche Inhalt der Updateoberfläche nicht definiert ist, führt ein Fehler beim Aktualisieren jedes Pixels zu einem nicht definierten Verhalten.

Nur eine DirectComposition-Oberfläche kann gleichzeitig aktualisiert werden. Eine Anwendung muss das Zeichnen auf einer Oberfläche anhalten, bevor das Zeichnen auf einer anderen Oberfläche beginnt oder fortgesetzt wird. Wenn die Anwendung BeginDraw zweimal aufruft, entweder für dieselbe Oberfläche oder für eine andere Oberfläche, die zum gleichen DirectComposition-Gerät gehört, ohne einen dazwischen liegenden Aufruf von IDCompositionSurface::EndDraw, schlägt der zweite Aufruf fehl. Wenn die Anwendung IDCompositionDevice2::Commit aufruft , ohne EndDraw aufzurufen, bleibt das Update ausstehend. Das Update wird erst wirksam, nachdem die Anwendung EndDraw aufgerufen hat und dann die IDCompositionDevice2::Commit-Methode aufruft.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2012 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile dcomp.h
Bibliothek Dcomp.lib
DLL Dcomp.dll

Weitere Informationen

IDCompositionSurface

IDCompositionSurface::EndDraw