IDCompositionVisual::AddVisual, méthode (dcomp.h)

Ajoute un nouveau visuel enfant à la liste des enfants de ce visuel.

Syntaxe

HRESULT AddVisual(
  [in]           IDCompositionVisual *visual,
  [in]           BOOL                insertAbove,
  [in, optional] IDCompositionVisual *referenceVisual
);

Paramètres

[in] visual

Type : IDCompositionVisual*

Visuel enfant à ajouter. Ce paramètre ne doit pas avoir la valeur NULL.

[in] insertAbove

Type : BOOL

TRUE pour placer le nouveau visuel enfant devant le visuel spécifié par le paramètre referenceVisual , ou FALSE pour le placer derrière referenceVisual.

[in, optional] referenceVisual

Type : IDCompositionVisual*

Visuel enfant existant à côté duquel le nouveau visuel doit être ajouté.

Valeur retournée

Type : HRESULT

Si la fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT. Pour obtenir la liste des codes d’erreur, consultez Codes d’erreur DirectComposition .

Notes

Les visuels enfants sont organisés dans une liste triée. Le contenu d’un visuel enfant est dessiné devant (ou au-dessus) le contenu de son visuel parent, mais derrière (ou en dessous) le contenu de ses enfants.

Le paramètre referenceVisual doit être un enfant existant du visuel parent, ou il doit avoir la valeur NULL. Le paramètre insertAbove indique si le nouvel enfant doit être rendu immédiatement au-dessus du visuel de référence dans l’ordre Z ou immédiatement en dessous de celui-ci.

Si le paramètre referenceVisual a la valeur NULL, le visuel spécifié est affiché au-dessus ou au-dessous de tous les enfants du visuel parent, en fonction de la valeur du paramètre insertAbove . Si insertAbove a la valeur TRUE, le nouveau visuel enfant est au-dessus d’aucun frère. Par conséquent, il est affiché sous tous ses frères. À l’inverse, si insertAbove a la valeur FALSE, le visuel est inférieur à aucun frère, donc il est rendu au-dessus de ses frères.

Le visuel spécifié par le paramètre visuel ne peut pas être un enfant d’un seul autre visuel ou la racine d’une arborescence visuelle associée à une cible de composition. Si le visuel est déjà un enfant d’un autre visuel, AddVisual échoue. Le visuel enfant doit être supprimé de la liste enfants de son parent précédent avant de l’ajouter à la liste enfants du nouveau parent. Si le visuel est la racine d’une arborescence visuelle, le visuel doit être dissocié de cette arborescence visuelle avant de l’ajouter à la liste des enfants du nouveau parent. Pour dissocier le visuel d’une arborescence visuelle, appelez la méthode IDCompositionTarget::SetRoot et spécifiez un visuel différent ou NULL comme paramètre visuel .

Un visuel enfant n’a pas besoin d’avoir été créé par la même interface IDCompositionDevice que son parent. Lorsque des visuels de différents appareils sont combinés dans la même arborescence visuelle, Microsoft DirectComposition compose l’arborescence comme il le ferait normalement, sauf que les modifications apportées à un visuel particulier prennent effet uniquement lorsque IDCompositionDevice::Commit est appelé sur l’objet d’appareil qui a créé le visuel. La possibilité de combiner des visuels de différents appareils permet à plusieurs threads de créer et de manipuler une seule arborescence visuelle tout en conservant des appareils indépendants qui peuvent être utilisés pour valider les modifications de manière asynchrone

Cette méthode échoue si visual ou referenceVisual n’est pas un pointeur non valide, ou si le visuel référencé par le paramètre referenceVisual n’est pas un enfant du visuel parent. Ces interfaces ne peuvent pas être des implémentations personnalisées ; seules les interfaces créées par DirectComposition peuvent être utilisées avec cette méthode.

Exemples

Pour obtenir un exemple, consultez Création d’une arborescence visuelle simple.

Spécifications

Voir aussi

IDCompositionDevice::CreateVisual

IDCompositionTarget::SetRoot

IDCompositionVisual

IDCompositionVisual::RemoveAllVisuals

IDCompositionVisual::RemoveVisual