Metodo IDCompositionSurface::BeginDraw (dcomp.h)

  • Articolo

Avvia il disegno su questo oggetto superficie di Microsoft DirectComposition. Il rettangolo di aggiornamento deve trovarsi entro i limiti della superficie; in caso contrario, questo metodo ha esito negativo.

Sintassi

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

Parametri

[in, optional] updateRect

Tipo: const RECT*

Rettangolo da aggiornare. Se questo parametro è NULL, l'intera bitmap viene aggiornata.

[in] iid

Tipo: REFIID

Identificatore dell'interfaccia da recuperare.

[out] updateObject

Tipo: void**

Riceve un puntatore dell'interfaccia del tipo specificato nel parametro iid . Questo parametro non deve essere NULL.

Nota In Windows 8, questo parametro è stato superficie.
 

[out] updateOffset

Tipo: POINT*

Offset nell'area in cui l'applicazione deve disegnare contenuto aggiornato. Questo offset farà riferimento all'angolo superiore sinistro del rettangolo di aggiornamento.

Valore restituito

Tipo: HRESULT

Se la funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Questo metodo consente a un'applicazione di aggiornare in modo incrementale il contenuto di un oggetto superficie DirectComposition. L'applicazione deve usare la sequenza seguente:

  1. Chiamare BeginDraw per avviare l'aggiornamento incrementale.
  2. Utilizzare la superficie recuperata come destinazione di rendering e disegnare il contenuto aggiornato nell'offset recuperato.
  3. Chiamare il metodo IDCompositionSurface::EndDraw per completare l'aggiornamento.
L'oggetto update restituito da questo metodo è un contesto di dispositivo Direct2D o una superficie DXGI, a seconda del valore del parametro iid e del modo in cui è stato creato l'oggetto surface DirectComposition. Se il parametro iid è __uuidof(ID2D1DeviceContext), l'oggetto restituito è un contesto di dispositivo Direct2D che ha già la superficie DirectComposition selezionata come destinazione di rendering. In caso contrario, è una superficie DXGI che l'applicazione può usare come destinazione di rendering. In entrambi i casi, l'oggetto restituito è associato al dispositivo Direct2D o DXGI passato dall'applicazione alla funzione DCompositionCreateDevice2 o al metodo IDCompositionDevice2::CreateSurfaceFactory .

Il parametro iid può essere __uuidof(ID2D1DeviceContext) se l'oggetto surface DirectComposition è stato creato da un dispositivo DirectComposition o da una factory di superficie, creata con un dispositivo Direct2D associato. In particolare, l'applicazione deve avere chiamato la funzione DCompositionCreateDevice2 o il metodo IDCompositionDevice2::CreateSurfaceFactory con un dispositivo Direct2D come parametro renderingDevice . Se la superficie DirectComposition è stata creata tramite una surface factory non associata a un dispositivo Direct2D o se è stata creata direttamente tramite l'interfaccia IDCompositionDevice2 e il dispositivo non è stato direttamente associato a un dispositivo Direct2D, quindi passando __uuidof(ID2D1DeviceContext) come parametro iid causa la restituzione di E_INVALIDARG.

Se l'applicazione recupera correttamente un contesto di dispositivo Direct2D come oggetto di aggiornamento, l'applicazione non deve chiamare il contesto del dispositivo ID2D1DeviceContext::BeginDraw o ID2D1DeviceContext::EndDraw nel contesto del dispositivo Direct2D restituito.

L'offset recuperato non è necessariamente uguale all'angolo superiore sinistro del rettangolo di aggiornamento richiesto. L'applicazione deve trasformare le primitive di rendering da disegnare all'interno di un rettangolo della stessa larghezza e altezza del rettangolo di input, ma in corrispondenza dell'offset specificato. L'applicazione non deve disegnare all'esterno di questo rettangolo.

Se il parametro updateRectangle è NULL, l'intera superficie viene aggiornata. In questo caso, poiché l'offset recuperato potrebbe comunque non essere (0,0), l'applicazione deve comunque trasformare di conseguenza le primitive di rendering.

Se la superficie non è una superficie virtuale, la prima volta che l'applicazione chiama questo metodo per una determinata superficie non virtuale, il rettangolo di aggiornamento deve coprire l'intera superficie, specificando la superficie completa nel rettangolo di aggiornamento richiesto o specificando NULL come parametro updateRectangle . Per le superfici virtuali, la prima chiamata può essere qualsiasi sotto rettangolo della superficie.

Poiché ogni chiamata a questo metodo potrebbe recuperare un oggetto diverso nell'area updateObject , l'applicazione non deve memorizzare nella cache il puntatore di superficie recuperato. L'applicazione deve rilasciare il puntatore recuperato non appena termina il disegno.

Il rettangolo di superficie recuperato non contiene il contenuto precedente della bitmap. L'applicazione deve aggiornare ogni pixel nel rettangolo di aggiornamento, cancellando prima la destinazione di rendering o rilasciando primitive di rendering sufficienti per coprire completamente il rettangolo di aggiornamento. Poiché il contenuto iniziale dell'area di aggiornamento non è definito, non è possibile aggiornare ogni pixel comporta un comportamento non definito.

È possibile aggiornare una sola superficie DirectComposition alla volta. Un'applicazione deve sospendere il disegno su una superficie prima di iniziare o riprendere a disegnare su un'altra superficie. Se l'applicazione chiama BeginDraw due volte, per la stessa superficie o per un'altra superficie appartenente allo stesso dispositivo DirectComposition, senza una chiamata di intervento a IDCompositionSurface::EndDraw, la seconda chiamata ha esito negativo. Se l'applicazione chiama IDCompositionDevice2::Commit senza chiamare EndDraw, l'aggiornamento rimane in sospeso. L'aggiornamento ha effetto solo dopo che l'applicazione chiama EndDraw e quindi chiama il metodo IDCompositionDevice2::Commit .

Requisiti

Requisito Valore
Client minimo supportato Windows 8 [solo app desktop]
Server minimo supportato Windows Server 2012 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione dcomp.h
Libreria Dcomp.lib
DLL Dcomp.dll

Vedi anche

IDCompositionSurface

IDCompositionSurface::EndDraw