Metodo IDCompositionVisual::AddVisual (dcomp.h)

Articolo
08/23/2023

Aggiunge un nuovo oggetto visivo figlio all'elenco figlio di questo oggetto visivo.

Sintassi

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

Parametri

[in] visual

Tipo: IDCompositionVisual*

Oggetto visivo figlio da aggiungere. Questo parametro non deve essere NULL.

[in] insertAbove

Tipo: BOOL

TRUE per posizionare il nuovo oggetto visivo figlio davanti all'oggetto visivo specificato dal parametro referenceVisual o FALSE per posizionarlo dietro referenceVisual.

[in, optional] referenceVisual

Tipo: IDCompositionVisual*

Oggetto visivo figlio esistente accanto al quale deve essere aggiunto il nuovo oggetto visivo.

Valore restituito

Tipo: HRESULT

Se la funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT . Per un elenco di codici di errore, vedere Codici di errore DirectComposition .

Commenti

Gli oggetti visivi figlio sono disposti in un elenco ordinato. Il contenuto di un oggetto visivo figlio viene disegnato davanti (o sopra) il contenuto dell'oggetto visivo padre, ma dietro (o sotto) il contenuto dei relativi elementi figlio.

Il parametro referenceVisual deve essere un elemento figlio dell'oggetto visivo padre oppure deve essere NULL. Il parametro insertAbove indica se il nuovo elemento figlio deve essere eseguito immediatamente sopra l'oggetto visivo di riferimento nell'ordine Z o immediatamente sotto di esso.

Se il parametro referenceVisual è NULL, l'oggetto visivo specificato viene eseguito sopra o sotto tutti gli elementi figlio dell'oggetto visivo padre, a seconda del valore del parametro insertAbove . Se insertAbove è TRUE, il nuovo oggetto visivo figlio è superiore a nessun fratello, pertanto viene eseguito il rendering sotto tutti i suoi fratelli. Al contrario, se insertAbove è FALSE, l'oggetto visivo è inferiore a nessun fratello, pertanto viene eseguito il rendering soprattutto di tutti i suoi fratelli.

L'oggetto visivo specificato dal parametro visivo non può essere un elemento figlio di un singolo oggetto visivo o la radice di un albero visivo associato a una destinazione di composizione. Se l'oggetto visivo è già figlio di un altro oggetto visivo, AddVisual ha esito negativo. L'oggetto visivo figlio deve essere rimosso dall'elenco figlio del padre precedente prima di aggiungerlo all'elenco figlio del nuovo padre. Se l'oggetto visivo è la radice di un albero visivo, l'oggetto visivo deve essere dissociato dall'albero visivo prima di aggiungerlo all'elenco figlio del nuovo padre. Per separare l'oggetto visivo da un albero visivo, chiamare il metodo IDCompositionTarget::SetRoot e specificare un oggetto visivo o NULL diverso come parametro visivo .

Un oggetto visivo figlio non deve essere stato creato dalla stessa interfaccia IDCompositionDevice del relativo padre. Quando gli oggetti visivi provenienti da dispositivi diversi vengono combinati nello stesso albero visivo, Microsoft DirectComposition compone l'albero come normalmente sarebbe, tranne che le modifiche apportate a un oggetto visivo specifico si applicano solo quando IDCompositionDevice::Commit viene chiamato sull'oggetto dispositivo che ha creato l'oggetto visivo. La possibilità di combinare oggetti visivi da dispositivi diversi consente a più thread di creare e modificare un singolo albero visivo mantenendo dispositivi indipendenti che possono essere usati per eseguire il commit delle modifiche in modo asincrono

Questo metodo ha esito negativo se l'oggetto visivo o referenceVisual è un puntatore non valido oppure se l'oggetto visivo a cui fa riferimento il parametro referenceVisual non è figlio dell'oggetto visivo padre. Queste interfacce non possono essere implementazioni personalizzate; solo le interfacce create da DirectComposition possono essere usate con questo metodo.

Esempio

Per un esempio, vedere Come creare un albero visivo semplice.

Requisiti


Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	dcomp.h
Libreria	Dcomp.lib
DLL	Dcomp.dll