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

Article
08/23/2023

Définit la propriété Effect de ce visuel. La propriété Effect modifie la façon dont la sous-arborescence enracinée dans ce visuel est mélangée à l’arrière-plan et peut appliquer une transformation de perspective 3D au visuel.

Syntaxe

HRESULT SetEffect(
  [in, optional] IDCompositionEffect *effect
);

Paramètres

[in, optional] effect

Type : IDCompositionEffect*

Pointeur vers un objet d’effet. Ce paramètre peut être NULL.

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

Cette méthode crée une surface hors écran implicite à laquelle se compose la sous-arborescence enracinée sur ce visuel. La surface est utilisée comme l’une des entrées de l’effet spécifié. La sortie de l’effet est composée directement vers la cible de composition. Certains effets utilisent également la cible de composition comme autre entrée implicite. C’est généralement le cas pour les effets de composition ou de fusion tels que l’opacité, où la cible de composition est considérée comme l'« arrière-plan ». Dans ce cas, tous les visuels qui se trouvent « en arrière-plan » du visuel actuel sont inclus dans la cible de composition lorsque le visuel actuel est rendu et sont considérés comme l'« arrière-plan » que ce visuel compose.

Si ce visuel n’est pas la racine d’une arborescence visuelle et que l’un de ses ancêtres a également un effet appliqué, la surface hors écran créée par l’ancêtre le plus proche est la cible de composition à laquelle l’effet de ce visuel est composé. Sinon, la cible de composition est la cible de composition racine. Par conséquent, l’arrière-plan des effets de composition et de mélange comprend uniquement les visuels jusqu’à l’ancêtre le plus proche qui a lui-même un effet. À l’inverse, tous les effets appliqués aux visuels sous le visuel actuel utilisent la surface hors écran nouvellement créée comme arrière-plan, ce qui peut affecter la façon dont ces visuels composent finalement en plus de ce que l’utilisateur final perçoit comme étant « derrière » ces visuels.

Si le paramètre d’effet a la valeur NULL, aucun effet bitmap n’est appliqué à ce visuel. Tous les effets précédents associés à ce visuel sont supprimés. La surface hors écran est également supprimée et la sous-arborescence visuelle est composée directement sur la cible de composition parente, ce qui peut également affecter la façon dont les effets de composition ou de fusion sous ce visuel sont rendus.

Cette méthode échoue si effect est un pointeur non valide ou s’il n’a pas été créé par la même interface IDCompositionDevice qui a créé ce visuel. L’interface ne peut pas être une implémentation personnalisée ; seules les interfaces créées par Microsoft DirectComposition peuvent être utilisées avec cette méthode.

Spécifications


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