Método IDCompositionVisual::AddVisual (dcomp.h)

Artículo
08/23/2023

Agrega un nuevo objeto visual secundario a la lista secundaria de este objeto visual.

Sintaxis

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

Parámetros

[in] visual

Tipo: IDCompositionVisual*

Objeto visual secundario que se va a agregar. Este parámetro no debe ser null.

[in] insertAbove

Tipo: BOOL

TRUE para colocar el nuevo objeto visual secundario delante del objeto visual especificado por el parámetro referenceVisual o FALSE para colocarlo detrás de referenceVisual.

[in, optional] referenceVisual

Tipo: IDCompositionVisual*

Objeto visual secundario existente junto al que se debe agregar el nuevo objeto visual.

Valor devuelto

Tipo: HRESULT

Si la función se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT. Consulte Códigos de error de DirectComposition para obtener una lista de códigos de error.

Comentarios

Los objetos visuales secundarios se organizan en una lista ordenada. El contenido de un objeto visual secundario se dibuja delante (o superior) del contenido de su objeto visual primario, pero detrás (o por debajo) del contenido de sus elementos secundarios.

El parámetro referenceVisual debe ser un elemento secundario existente del objeto visual primario o debe ser NULL. El parámetro insertAbove indica si el nuevo elemento secundario debe representarse inmediatamente encima del objeto visual de referencia en el orden Z o inmediatamente debajo de él.

Si el parámetro referenceVisual es NULL, el objeto visual especificado se representa encima o debajo de todos los elementos secundarios del objeto visual primario, según el valor del parámetro insertAbove . Si insertAbove es TRUE, el nuevo objeto visual secundario está por encima de ningún elemento relacionado, por lo que se representa debajo de todos sus elementos del mismo nivel. Por el contrario, si insertAbove es FALSE, el objeto visual no está por debajo de ningún elemento relacionado, por lo que se representa sobre todos sus elementos del mismo nivel.

El objeto visual especificado por el parámetro visual no puede ser un elemento secundario de otro objeto visual o la raíz de un árbol visual asociado a un destino de composición. Si el objeto visual ya es un elemento secundario de otro objeto visual, se produce un error en AddVisual . El objeto visual secundario debe quitarse de la lista secundaria de su elemento primario anterior antes de agregarlo a la lista secundaria del nuevo elemento primario. Si el objeto visual es la raíz de un árbol visual, el objeto visual debe desasociarse de ese árbol visual antes de agregarlo a la lista secundaria del nuevo elemento primario. Para desasociar el objeto visual de un árbol visual, llame al método IDCompositionTarget::SetRoot y especifique un objeto visual o NULL diferente como parámetro visual .

No es necesario crear un objeto visual secundario con la misma interfaz IDCompositionDevice que su elemento primario. Cuando los objetos visuales de diferentes dispositivos se combinan en el mismo árbol visual, Microsoft DirectComposition compone el árbol como lo haría normalmente, excepto que los cambios en un objeto visual determinado surten efecto solo cuando se llama a IDCompositionDevice::Commit en el objeto de dispositivo que creó el objeto visual. La capacidad de combinar objetos visuales de diferentes dispositivos permite que varios subprocesos creen y manipulen un único árbol visual, a la vez que se mantienen dispositivos independientes que se pueden usar para confirmar los cambios de forma asincrónica.

Este método produce un error si visual o referenceVisual es un puntero no válido o si el objeto visual al que hace referencia el parámetro referenceVisual no es un elemento secundario del objeto visual primario. Estas interfaces no pueden ser implementaciones personalizadas; solo se pueden usar interfaces creadas por DirectComposition con este método.

Ejemplos

Para obtener un ejemplo, vea Cómo crear un árbol visual simple.

Requisitos


Cliente mínimo compatible	Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	dcomp.h
Library	Dcomp.lib
Archivo DLL	Dcomp.dll