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.
[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:
- Rufen Sie BeginDraw auf, um das inkrementelle Update zu initiieren.
- Verwenden Sie die abgerufene Oberfläche als Renderziel, und zeichnen Sie die aktualisierten Inhalte am abgerufenen Offset.
- Rufen Sie die IDCompositionSurface::EndDraw-Methode auf, um das Update abzuschließen.
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 |