IDCompositionVisual::SetEffect-Methode (dcomp.h)

Artikel
08/23/2023

Legt die Effect-Eigenschaft dieses Visuals fest. Die Effect-Eigenschaft ändert, wie die Teilstruktur, die in diesem Visual verwurzelt ist, mit dem Hintergrund gemischt wird, und kann eine 3D-Perspektiventransformation auf das Visual anwenden.

Syntax

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

Parameter

[in, optional] effect

Typ: IDCompositionEffect*

Ein Zeiger auf ein Effektobjekt. Dieser Parameter kann NULL sein.

Rückgabewert

Typ: HRESULT

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben. Eine Liste der Fehlercodes finden Sie unter DirectComposition-Fehlercodes .

Hinweise

Mit dieser Methode wird eine implizite Off-Screen-Oberfläche erstellt, auf die die Teilstruktur, die in diesem Visual verwurzelt ist, zusammengesetzt ist. Die Oberfläche wird als eine der Eingaben für den angegebenen Effekt verwendet. Die Ausgabe des Effekts wird direkt mit dem Kompositionsziel zusammengesetzt. Einige Effekte verwenden auch das Kompositionsziel als eine weitere implizite Eingabe. Dies ist in der Regel bei Kompositions- oder Blendeffekten wie Deckkraft der Fall, wobei das Kompositionsziel als "Hintergrund" betrachtet wird. In diesem Fall werden alle Visuals, die sich "hinter" dem aktuellen Visual befinden, in das Kompositionsziel eingeschlossen, wenn das aktuelle Visual gerendert wird, und als der "Hintergrund" betrachtet, zu dem dieses Visual zusammengesetzt ist.

Wenn dieses Visual nicht der Stamm einer visuellen Struktur ist und eine seiner Vorgänger auch einen Effekt darauf angewendet hat, ist die off-screen-Oberfläche, die vom nächstgelegenen Vorgänger erstellt wurde, das Kompositionsziel, für das der Effekt dieses Visuals zusammengesetzt ist. Andernfalls ist das Kompositionsziel das Ziel der Stammkomposition. Folglich umfasst der Hintergrund für Kompositions- und Blendeffekte nur die Visuals bis zum nächstgelegenen Vorgänger, der selbst eine Wirkung hat. Umgekehrt verwenden alle Effekte, die auf Visuals unter dem aktuellen Visual angewendet werden, die neu erstellte Off-Screen-Oberfläche als Hintergrund, was sich darauf auswirken kann, wie diese Visuals letztendlich zusätzlich zu dem bestehen, was der Endbenutzer als "hinter" diesen Visuals betrachtet.

Wenn der Effektparameter NULL ist, wird kein Bitmapeffekt auf dieses Visual angewendet. Alle vorherigen Effekte, die diesem Visual zugeordnet waren, werden entfernt. Die Off-Screen-Oberfläche wird ebenfalls entfernt, und die visuelle Unterstruktur wird direkt mit dem übergeordneten Kompositionsziel zusammengesetzt, was sich auch darauf auswirken kann, wie Kompositions- oder Blendeffekte unter diesem Visual gerendert werden.

Diese Methode schlägt fehl, wenn effect ein ungültiger Zeiger ist oder nicht von derselben IDCompositionDevice-Schnittstelle erstellt wurde, die dieses Visual erstellt hat. Die Schnittstelle kann keine benutzerdefinierte Implementierung sein. mit dieser Methode können nur schnittstellen verwendet werden, die von Microsoft DirectComposition erstellt wurden.

Anforderungen


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