IdCompositionSurface ::BeginDraw, méthode (dcomp.h)

  • Article

Lance le dessin sur cet objet de surface Microsoft DirectComposition. Le rectangle de mise à jour doit se trouver dans les limites de la surface ; sinon, cette méthode échoue.

Syntaxe

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

Paramètres

[in, optional] updateRect

Type : const RECT*

Rectangle à mettre à jour. Si ce paramètre a la valeur NULL, la bitmap entière est mise à jour.

[in] iid

Type : REFIID

Identificateur de l’interface à récupérer.

[out] updateObject

Type : void**

Reçoit un pointeur d’interface du type spécifié dans le paramètre iid . Ce paramètre ne doit pas être NULL.

Note Dans Windows 8, ce paramètre était surface.
 

[out] updateOffset

Type : POINT*

Décalage dans la surface où l’application doit dessiner le contenu mis à jour. Ce décalage fait référence au coin supérieur gauche du rectangle de mise à jour.

Valeur retournée

Type : HRESULT

Si la fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Cette méthode permet à une application de mettre à jour de manière incrémentielle le contenu d’un objet surface DirectComposition. L’application doit utiliser la séquence suivante :

  1. Appelez BeginDraw pour lancer la mise à jour incrémentielle.
  2. Utilisez la surface récupérée comme cible de rendu et dessinez le contenu mis à jour au décalage récupéré.
  3. Appelez la méthode IDCompositionSurface ::EndDraw pour terminer la mise à jour.
L’objet de mise à jour retourné par cette méthode est un contexte d’appareil Direct2D ou une surface DXGI, selon la valeur du paramètre iid et la façon dont l’objet surface DirectComposition a été créé. Si le paramètre iid est __uuidof(ID2D1DeviceContext), l’objet retourné est un contexte d’appareil Direct2D dont la surface DirectComposition est déjà sélectionnée comme cible de rendu. Sinon, il s’agit d’une surface DXGI que l’application peut utiliser comme cible de rendu. Dans les deux cas, l’objet retourné est associé à l’appareil Direct2D ou DXGI passé par l’application à la fonction DCompositionCreateDevice2 ou à la méthode IDCompositionDevice2 ::CreateSurfaceFactory .

Le paramètre iid ne peut être __uuidof(ID2D1DeviceContext) que si l’objet surface DirectComposition a été créé à partir d’un appareil DirectComposition ou d’une fabrique de surface qui a été, lui-même, créé avec un appareil Direct2D associé. En particulier, l’application doit avoir appelé la fonction DCompositionCreateDevice2 ou la méthode IDCompositionDevice2 ::CreateSurfaceFactory avec un appareil Direct2D comme paramètre renderingDevice . Si la surface DirectComposition a été créée via une fabrique de surface qui n’a pas été associée à un appareil Direct2D, ou si elle a été créée directement via l’interface IDCompositionDevice2 et que l’appareil n’a pas été directement associé à un appareil Direct2D, le passage de __uuidof(ID2D1DeviceContext) en tant que paramètre iid entraîne le retour de cette méthode E_INVALIDARG.

Si l’application récupère correctement un contexte d’appareil Direct2D en tant qu’objet de mise à jour, l’application ne doit pas appeler les méthodes ID2D1DeviceContext ::BeginDraw ou ID2D1DeviceContext ::EndDraw sur le contexte d’appareil Direct2D retourné.

Le décalage récupéré n’est pas nécessairement le même que le coin supérieur gauche du rectangle de mise à jour demandé. L’application doit transformer ses primitives de rendu pour dessiner dans un rectangle de la même largeur et de la même hauteur que le rectangle d’entrée, mais au décalage donné. L’application ne doit pas dessiner en dehors de ce rectangle.

Si le paramètre updateRectangle a la valeur NULL, la surface entière est mise à jour. Dans ce cas, étant donné que le décalage récupéré n’est toujours pas (0,0), l’application doit toujours transformer ses primitives de rendu en conséquence.

Si la surface n’est pas une surface virtuelle, la première fois que l’application appelle cette méthode pour une surface non virtuelle particulière, le rectangle de mise à jour doit couvrir toute la surface, soit en spécifiant la surface complète dans le rectangle de mise à jour demandé, soit en spécifiant NULL comme paramètre updateRectangle . Pour les surfaces virtuelles, le premier appel peut être n’importe quel sous-rectangle de la surface.

Étant donné que chaque appel à cette méthode peut récupérer un objet différent dans la surface updateObject , l’application ne doit pas mettre en cache le pointeur de surface récupéré. L’application doit libérer le pointeur récupéré dès qu’il a terminé le dessin.

Le rectangle de surface récupéré ne contient pas le contenu précédent de la bitmap. L’application doit mettre à jour chaque pixel du rectangle de mise à jour, soit en effaçant d’abord la cible de rendu, soit en émettant suffisamment de primitives de rendu pour couvrir entièrement le rectangle de mise à jour. Étant donné que le contenu initial de la surface de mise à jour n’est pas défini, l’échec de la mise à jour de chaque pixel entraîne un comportement non défini.

Une seule surface DirectComposition peut être mise à jour à la fois. Une application doit suspendre le dessin sur une surface avant de commencer ou de reprendre le dessin sur une autre surface. Si l’application appelle BeginDraw deux fois, soit pour la même surface, soit pour une autre surface appartenant au même appareil DirectComposition, sans appel intermédiaire à IDCompositionSurface ::EndDraw, le deuxième appel échoue. Si l’application appelle IDCompositionDevice2 ::Commit sans appeler EndDraw, la mise à jour reste en attente. La mise à jour prend effet uniquement après que l’application a appelé EndDraw , puis la méthode IDCompositionDevice2 ::Commit .

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau uniquement]
Plateforme cible Windows
En-tête dcomp.h
Bibliothèque Dcomp.lib
DLL Dcomp.dll

Voir aussi

IDCompositionSurface

IDCompositionSurface ::EndDraw