IDCompositionVisual::AddVisual-Methode (dcomp.h)

Artikel
08/23/2023

Fügt der Untergeordneten Liste dieses Visuals ein neues untergeordnetes Visual hinzu.

Syntax

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

Parameter

[in] visual

Typ: IDCompositionVisual*

Das untergeordnete Visual, das hinzugefügt werden soll. Dieser Parameter darf nicht NULL sein.

[in] insertAbove

Typ: BOOL

TRUE, um das neue untergeordnete Visual vor dem visual zu platzieren, das durch den parameter referenceVisual angegeben wird, oder FALSE, um es hinter referenceVisual zu platzieren.

[in, optional] referenceVisual

Typ: IDCompositionVisual*

Das vorhandene untergeordnete Visual, neben dem das neue Visual hinzugefügt werden soll.

Rückgabewert

Typ: HRESULT

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

Hinweise

Untergeordnete Visuals werden in einer sortierten Liste angeordnet. Der Inhalt eines untergeordneten Visuals wird vor (oder höher) dem Inhalt des übergeordneten Visuals gezeichnet, aber hinter (oder darunter) dem Inhalt seiner untergeordneten Elemente.

Der referenceVisual-Parameter muss ein vorhandenes untergeordnetes Element des übergeordneten Visuals oder NULL sein. Der parameter insertAbove gibt an, ob das neue untergeordnete Element direkt über dem Referenzvisual in der Z-Reihenfolge oder direkt darunter gerendert werden soll.

Wenn der referenceVisual-Parameter NULL ist, wird das angegebene Visual je nach Wert des insertAbove-Parameters oberhalb oder unterhalb aller untergeordneten Elemente des übergeordneten Visuals gerendert. Wenn insertAbove TRUE ist, befindet sich das neue untergeordnete Visual über keinem gleichgeordneten Visual, daher wird es unter allen geschwistern gerendert. Wenn insertAbove hingegen FALSE ist, befindet sich das Visual unter keinem gleichgeordneten Element, daher wird es vor allem von seinen Geschwistern gerendert.

Das durch den visuellen Parameter angegebene Visual kann weder ein untergeordnetes Element eines einzelnen anderen Visuals noch der Stamm einer visuellen Struktur sein, die einem Kompositionsziel zugeordnet ist. Wenn visual bereits ein untergeordnetes Element eines anderen Visuals ist, schlägt AddVisual fehl. Das untergeordnete Visual muss aus der Untergeordneten Liste des vorherigen übergeordneten Elements entfernt werden, bevor es der untergeordneten Liste des neuen übergeordneten Elements hinzugefügt wird. Wenn visual der Stamm einer visuellen Struktur ist, muss das Visual von dieser visuellen Struktur getrennt werden, bevor es der untergeordneten Liste des neuen übergeordneten Elements hinzugefügt wird. Um das Visual von einer visuellen Struktur zu trennen, rufen Sie die IDCompositionTarget::SetRoot-Methode auf, und geben Sie entweder ein anderes Visual oder NULL als visuellen Parameter an.

Ein untergeordnetes Visual muss nicht von derselben IDCompositionDevice-Schnittstelle wie das übergeordnete Element erstellt worden sein. Wenn Visuals von verschiedenen Geräten in derselben visuellen Struktur kombiniert werden, erstellt Microsoft DirectComposition die Struktur wie gewohnt, mit der Ausnahme, dass Änderungen an einem bestimmten Visual nur wirksam werden, wenn IDCompositionDevice::Commit für das Geräteobjekt aufgerufen wird, das das Visual erstellt hat. Die Möglichkeit, Visuals von verschiedenen Geräten zu kombinieren, ermöglicht es mehreren Threads, eine einzelne visuelle Struktur zu erstellen und zu bearbeiten, während unabhängige Geräte beibehalten werden können, die zum asynchronen Commit von Änderungen verwendet werden können.

Diese Methode schlägt fehl, wenn visual oder referenceVisual ein ungültiger Zeiger ist oder wenn das Visual, auf das vom parameter referenceVisual verwiesen wird, kein untergeordnetes Element des übergeordneten Visuals ist. Diese Schnittstellen dürfen keine benutzerdefinierten Implementierungen sein. Mit dieser Methode können nur schnittstellen verwendet werden, die von DirectComposition erstellt wurden.

Beispiele

Ein Beispiel finden Sie unter Erstellen einer einfachen visuellen Struktur.

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