MultiEffect QML Type
Aplica un efecto de posprocesamiento a un elemento. Más...
| Import Statement: | import QtQuick.Effects |
| Inherits: |
Propiedades
- autoPaddingEnabled : bool
- blur : real
- blurEnabled : bool
- blurMax : int
- blurMultiplier : real
- brightness : real
- colorization : real
- colorizationColor : color
- contrast : real
- fragmentShader : string
- hasProxySource : bool
- itemRect : rect
- maskEnabled : bool
- maskInverted : bool
- maskSource : Item
- maskSpreadAtMax : real
- maskSpreadAtMin : real
- maskThresholdMax : real
- maskThresholdMin : real
- paddingRect : rect
- saturation : real
- shadowBlur : real
- shadowColor : color
- shadowEnabled : bool
- shadowHorizontalOffset : real
- shadowOpacity : real
- shadowScale : real
- shadowVerticalOffset : real
- source : Item
- vertexShader : string
Señales
Descripción detallada
El tipo MultiEffect, sucesor del módulo Qt Graphical Effects de Qt 5, aplica un efecto de posprocesamiento al elemento source. A diferencia del módulo « Graphical Effects » de Qt, «MultiEffect» permite combinar varios efectos (desenfoque, sombra, coloración, etc.) en un único elemento y sombreador. Puedes utilizar « MultiEffect » si solo necesitas un único efecto sin sobrecarga adicional, pero también puedes utilizarlo para aplicar varios efectos a un elemento sin el coste que suponen múltiples pasadas de renderizado.
MultiEffect está diseñado específicamente para los efectos más comunes y se puede animar fácilmente. Si MultiEffect no contiene el efecto que necesitas, plantéate implementar un efecto personalizado utilizando Qt Quick Effect Maker. Para obtener más información sobre los efectos de shader, consulta la documentación de referencia de ShaderEffect.
Ten en cuenta que el tipo MultiEffect renderiza un nuevo elemento visual junto al elemento de origen. Para aplicar el efecto al elemento de origen, debe colocar el nuevo elemento MultiEffect en la posición del elemento de origen. Si el elemento de origen y el elemento MultiEffect no son opacos, ambos elementos pueden quedar visibles, por lo que es posible que no se obtenga el efecto deseado. Para ocultar el elemento de origen, realice una de las siguientes acciones:
- Establece «
visible: false» (Ocultar) para el elemento de origen. En este caso, el elemento de origen no se muestra en absoluto y no puede recibir entradas táctiles ni clics. - Establece «
opacity: 0» para el elemento de origen. En este caso, el elemento de origen es completamente transparente, pero sigue pudiendo recibir entradas táctiles o de clic.
Ejemplo de uso
El siguiente ejemplo muestra cómo aplicar un efecto de saturación a un elemento:
| |
El siguiente ejemplo muestra cómo aplicar un efecto de saturación a un layered Item:
| |
El siguiente ejemplo muestra cómo aplicar varios efectos al mismo tiempo:
| |
A continuación se muestra un ejemplo de cómo utilizar conjuntamente los efectos de máscara, coloración y brillo para desvanecer un elemento. Este tipo de ocultación o visualización de elementos puede, por ejemplo, vincularse al valor de un control deslizante o a animaciones como NumberAnimation. Obsérvese que la propiedad visible tiene el valor «false» cuando el elemento está totalmente desvanecido, para evitar un renderizado innecesario del efecto.
| |
Rendimiento
Hay algunos aspectos que debes tener en cuenta para obtener un rendimiento óptimo:
- Para obtener el shader más óptimo, activa solo los efectos que realmente utilices (consulta blurEnabled, shadowEnabled, maskEnabled). Los efectos de color sencillos (brightness, contrast, saturation, colorization) siempre están activados, por lo que su uso no supone una sobrecarga adicional.
- Consulta las notas sobre rendimiento de las propiedades que pueden modificar el tamaño del shader o del elemento de efecto y no las modifiques durante las animaciones.
- Cuando no se utilice MultiEffect, recuerda establecer su propiedad
visibleen «false» para evitar que se rendericen los efectos en segundo plano. - El desenfoque y la sombra son los efectos que más recursos consumen. Con estos, es preferible aumentar el valor de « blurMultiplier » en lugar de « blurMax » y evitar el uso de elementos « source » que se animen, para que no sea necesario regenerar el desenfoque en cada fotograma.
- Aplica los efectos a elementos QML de tamaño óptimo, ya que un mayor número de píxeles supone más trabajo para la GPU. Al aplicar el efecto de desenfoque a todo el fondo, recuerda establecer autoPaddingEnabled en «false»; de lo contrario, el efecto se extenderá «fuera» de la ventana o la pantalla.
Puedes combinar la propiedad « ShaderEffectSource » con la propiedad « MultiEffect »:
- Para utilizar el mismo elemento de origen en varios efectos y mantenerlo sin cambios.
- Para utilizar una parte del elemento de origen, mediante la propiedad « ShaderEffectSource.sourceRect ».
- Para reducir la resolución del elemento de origen, por ejemplo, para mejorar el rendimiento, utilizando la propiedad « ShaderEffectSource.textureSize ».
Documentación de la propiedad
autoPaddingEnabled : bool
Cuando están activados los efectos de desenfoque o sombra y esta opción está establecida en «true» (valor por defecto), el tamaño del elemento se rellena automáticamente según lo indicado en blurMax y blurMultiplier. Ten en cuenta que siempre se añade paddingRect al tamaño.

Nota sobre el rendimiento: el tamaño del elemento debe ser lo más pequeño posible para obtener un rendimiento óptimo.
Nota sobre el rendimiento: provoca un cambio de tamaño del elemento; no modifiques esta propiedad durante la animación.
Véase también paddingRect.
blur : real
Esta propiedad define el grado de desenfoque (radio) que se aplica a la fuente.
El valor oscila entre 0,0 (sin desenfoque) y 1,0 (desenfoque total). Por defecto, la propiedad está establecida en 0.0 (sin cambios). La intensidad del desenfoque total se ve afectada por blurMax y blurMultiplier.
Nota sobre el rendimiento: si no necesitas acercarte a 1,0 en ningún momento de las animaciones de desenfoque, plantéate reducir blurMax o blurMultiplier para obtener un rendimiento óptimo.
blurEnabled : bool
Activa el efecto de desenfoque.
Nota sobre el rendimiento: provoca un cambio en el shader; no modifiques esta propiedad durante la animación.
blurMax : int
Esta propiedad define el radio máximo en píxeles que alcanzará el desenfoque con un valor de 1,0.
El rango significativo de este valor va de 2 (desenfoque sutil) a 64 (desenfoque intenso). Por defecto, la propiedad está establecida en 32. Para obtener un rendimiento óptimo, selecciona el valor más pequeño que necesites.
Nota: Esto afecta tanto a los efectos de desenfoque como a los de sombra.
Nota sobre el rendimiento: provoca un cambio en el sombreador; no modifiques esta propiedad durante la animación.
Nota sobre el rendimiento: provoca un cambio de tamaño del elemento; no modifique esta propiedad durante la animación.
blurMultiplier : real
Esta propiedad define un multiplicador para ampliar el radio de desenfoque.
El valor oscila entre 0,0 (sin multiplicar) e infinito. Por defecto, la propiedad está establecida en 0.0. Al aumentar el multiplicador se amplía el radio de desenfoque, pero disminuye la calidad del mismo. Esta es una opción más eficiente para un radio de desenfoque mayor que blurMax, ya que no aumenta el número de consultas a la textura.
Nota: Esto afecta tanto a los efectos de desenfoque como a los de sombra.
Nota sobre el rendimiento: provoca un cambio de tamaño del elemento; no modifiques esta propiedad durante la animación.
brightness : real
Esta propiedad define en qué medida se aumenta o se reduce el brillo de la fuente.
El valor oscila entre -1,0 y 1,0. De forma predeterminada, la propiedad está establecida en « 0.0 » (sin cambios).
colorization : real
Esta propiedad define en qué medida se colorea la fuente con el valor « colorizationColor ».
El valor oscila entre 0,0 (sin colorear) y 1,0 (totalmente coloreado). Por defecto, la propiedad está establecida en « 0.0 » (sin cambios).
colorizationColor : color
Esta propiedad define el valor de color RGBA que se utiliza para dar color a la fuente.
De forma predeterminada, la propiedad está establecida en Qt.rgba(1.0, 0.0, 0.0, 1.0) (rojo).
Véase también colorization.
contrast : real
Esta propiedad define en qué medida se aumenta o se reduce el contraste de origen.
El valor oscila entre -1,0 y 1,0. De forma predeterminada, la propiedad está establecida en « 0.0 » (sin cambios).
fragmentShader : string [read-only]
Acceso de solo lectura al nombre del archivo del shader de fragmentos que se está utilizando actualmente.
hasProxySource : bool [read-only]
Devuelve «true» cuando el « MultiEffect » crea internamente un « ShaderEffectSource » para el elemento « source », y «false» cuando el elemento « source » se utiliza tal cual. Por ejemplo, cuando la fuente es un elemento « Image » o un « Item » con « layer.enabled » establecido en « true », esta fuente proxy adicional no es necesaria.
itemRect : rect [read-only]
Acceso de solo lectura al rectángulo del elemento de efecto. Esto puede utilizarse, por ejemplo, para ver el área que cubre el elemento.
Véase también paddingRect y autoPaddingEnabled.
maskEnabled : bool
Activa el efecto de máscara.
Nota sobre el rendimiento: provoca un cambio en el shader; no modifiques esta propiedad durante la animación.
maskInverted : bool
Esta propiedad invierte la máscara: en lugar de ocultar el contenido que se encuentra fuera de maskThresholdMin y maskThresholdMax, se ocultará el contenido que se encuentre entre ambos.
Por defecto, la propiedad está establecida en false.
maskSource : Item
Elemento de origen para el efecto de máscara. Debe apuntar a ShaderEffectSource, a un elemento cuyo campo « layer.enabled » esté configurado en true, o a un elemento que pueda utilizarse directamente como fuente de textura (por ejemplo, Image). El canal alfa del elemento de origen se utiliza para el enmascaramiento.
Si maskSource y la fuente tienen dimensiones diferentes, la imagen de maskSource se estira para ajustarse al tamaño de la fuente.
maskSpreadAtMax : real
Esta propiedad define la suavidad de los bordes de la máscara cerca del « maskThresholdMax ». Al utilizar valores de dispersión más altos, se suaviza la transición de los píxeles transparentes de la máscara hacia los opacos, añadiendo valores interpolados entre ellos.
El valor oscila entre 0,0 (borde de máscara nítido) y 1,0 (borde de máscara suave). De forma predeterminada, la propiedad está establecida en 0.0.
maskSpreadAtMin : real
Esta propiedad define la suavidad de los bordes de la máscara cerca del « maskThresholdMin ». Al establecer valores de dispersión más altos, se suaviza la transición de los píxeles transparentes de la máscara hacia los píxeles opacos, añadiendo valores interpolados entre ellos.
El valor oscila entre 0,0 (borde de máscara nítido) y 1,0 (borde de máscara suave). De forma predeterminada, la propiedad está establecida en 0.0.
maskThresholdMax : real
Esta propiedad define un valor umbral máximo para los píxeles de la máscara. Los píxeles de la máscara que tienen un valor alfa inferior al de esta propiedad se utilizan para enmascarar por completo los píxeles correspondientes del elemento de origen. Los píxeles de la máscara que tienen un valor alfa superior se utilizan para realizar una mezcla alfa del elemento de origen con la pantalla.
El valor oscila entre 0,0 (valor alfa 0) y 1,0 (valor alfa 255). De forma predeterminada, la propiedad está establecida en 1.0.
maskThresholdMin : real
Esta propiedad define un valor umbral mínimo para los píxeles de la máscara. Los píxeles de la máscara que tienen un valor alfa inferior al de esta propiedad se utilizan para enmascarar por completo los píxeles correspondientes del elemento de origen. Los píxeles de la máscara que tienen un valor alfa superior se utilizan para realizar una mezcla alfa del elemento de origen con la pantalla.
El valor oscila entre 0,0 (valor alfa 0) y 1,0 (valor alfa 255). De forma predeterminada, la propiedad está establecida en 0.0.
paddingRect : rect
Configura esta opción para aumentar manualmente el tamaño del elemento, de modo que el desenfoque y/o las sombras quepan correctamente. Si « autoPaddingEnabled » es «true» y no se ha definido «paddingRect», el elemento se rellena para que quepa el elemento con el máximo desenfoque posible, según lo indicado en blurMax y blurMultiplier. Al habilitar la sombra, normalmente es necesario tener en cuenta shadowHorizontalOffset y shadowVerticalOffset y ajustar «paddingRect» en consecuencia.
A continuación se muestra un ejemplo de cómo ajustar paddingRect con autoPaddingEnabled establecido en false, de modo que la sombra quepa dentro del elemento de MultiEffect.

Nota sobre el rendimiento: El tamaño del elemento debe ser lo más pequeño posible para obtener un rendimiento óptimo.
Nota sobre el rendimiento: provoca un cambio de tamaño del elemento; no modifique esta propiedad durante la animación.
Véase también ` autoPaddingEnabled`.
saturation : real
Esta propiedad define en qué medida se aumenta o se reduce la saturación de la fuente.
El valor oscila entre -1,0 (totalmente desaturado) e infinito. Por defecto, la propiedad está establecida en « 0.0 » (sin cambios).
shadowBlur : real
Esta propiedad define el grado de desenfoque (radio) que se aplica a la sombra.
El valor oscila entre 0,0 (sin desenfoque) y 1,0 (desenfoque total). Por defecto, la propiedad está establecida en 1.0. La intensidad del desenfoque total depende de blurMax y blurMultiplier.
Nota sobre el rendimiento: La forma más óptima de reducir el desenfoque de las sombras es reducir el valor de « blurMax » (si no es necesario para el desenfoque de los elementos). Solo hay que recordar no ajustar « blurMax » durante las animaciones.
shadowColor : color
Esta propiedad define el valor de color RGBA que se utiliza para la sombra. Resulta útil, por ejemplo, cuando se utiliza una sombra para simular un efecto de resplandor.
Por defecto, la propiedad está establecida en « Qt.rgba(0.0, 0.0, 0.0, 1.0) » (negro).
shadowEnabled : bool
Activa el efecto de sombra.
Nota sobre el rendimiento: provoca un cambio en el sombreador; no modifiques esta propiedad durante la animación.
shadowHorizontalOffset : real
Esta propiedad define el desplazamiento horizontal de la sombra respecto al centro del elemento.
El valor oscila entre -inf e inf. Por defecto, la propiedad está establecida en 0.0.
Nota: Al alejar la posición de la sombra del centro y añadir un « shadowBlur », es posible que también tengas que aumentar el « paddingRect » en consecuencia si quieres que la sombra no quede recortada.
shadowOpacity : real
Esta propiedad define la opacidad de la sombra proyectada. Este valor se multiplica por el valor alfa de « shadowColor ».
El valor oscila entre 0,0 (totalmente transparente) y 1,0 (totalmente opaco). Por defecto, la propiedad está establecida en « 1.0 ».
shadowScale : real
Esta propiedad define la escala de la sombra. La escala se aplica desde el centro del elemento.
El valor oscila entre 0 e infinito. Por defecto, la propiedad está establecida en 1.0.
Nota: Al aumentar el valor de shadowScale, es posible que también tengas que aumentar el valor de paddingRect en consecuencia para evitar que la sombra quede recortada.
shadowVerticalOffset : real
Esta propiedad define el desplazamiento vertical de la sombra con respecto al centro del elemento.
El valor oscila entre -inf e inf. Por defecto, la propiedad está establecida en 0.0.
Nota: Al alejar la posición de la sombra del centro y añadir « shadowBlur », es posible que también tengas que aumentar el valor de « paddingRect » en consecuencia si quieres que la sombra no quede recortada.
source : Item
Esta propiedad contiene el elemento que se utilizará como fuente para el efecto. Si es necesario, « MultiEffect » generará internamente un « ShaderEffectSource » como fuente de textura.
Nota: Noestá permitido que el efecto se incluya a sí mismo, por ejemplo, estableciendo la fuente como el elemento padre del efecto.
Nota: Si el elemento fuente tiene layer.enabled establecido en «true», se utilizará directamente. Esto es beneficioso para el rendimiento y suele ser lo más recomendable cuando la fuente está oculta. Sin embargo, si la fuente permanece visible y el efecto añade relleno (autoPaddingEnabled, paddingRect), dicho relleno puede afectar al aspecto del elemento fuente.
Véase también hasProxySource.
vertexShader : string [read-only]
Acceso de solo lectura al nombre del archivo del sombreador de vértices que se está utilizando actualmente.
Documentación de Signal
shaderChanged()
Esta señal se emite cuando cambia el shader utilizado.
Nota: El controlador correspondiente es onShaderChanged.
Véase también fragmentShader y vertexShader.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.


