En esta página

MultiEffect QML Type

Aplica un efecto de posprocesamiento a un elemento. Más...

Import Statement: import QtQuick.Effects
Inherits:

Item

Propiedades

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:

Logotipo de Qt en escala de grises que muestra el efecto de desaturación total

import QtQuick
import QtQuick.Effects

...
Image {
    id: sourceItem
    source: "qt_logo_green_rgb.png"
    // Hide the source item, otherwise both the source item and
    // MultiEffect will be rendered
    visible: false
    // or you can set:
    // opacity: 0
}
// Renders a new item with the specified effects rendered
// at the same position where the source item was rendered
MultiEffect {
    source: sourceItem
    anchors.fill: sourceItem
    saturation: -1.0
}

El siguiente ejemplo muestra cómo aplicar un efecto de saturación a un layered Item:

Logotipo de Qt en escala de grises que muestra el efecto de desaturación total

import QtQuick
import QtQuick.Effects

...
Image {
    id: sourceItem
    source: "qt_logo_green_rgb.png"
    layer.enabled: true
    // For the layered items, you can assign a MultiEffect directly
    // to layer.effect.
    layer.effect: MultiEffect {
        saturation: -1.0
    }
}

El siguiente ejemplo muestra cómo aplicar varios efectos al mismo tiempo:

Logotipo de Qt con un resplandor verde que muestra una combinación de efectos de brillo, saturación y desenfoque

import QtQuick
import QtQuick.Effects

...
MultiEffect {
    source: sourceItem
    anchors.fill: sourceItem
    brightness: 0.4
    saturation: 0.2
    blurEnabled: true
    blurMax: 64
    blur: 1.0
}

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.

Cuatro etapas del desvanecimiento del logotipo de Qt con máscara y coloración, desde el verde visible hasta las partículas rosas que se disuelven

import QtQuick
import QtQuick.Effects
import QtQuick.Controls.Material

...
MultiEffect {
    property real effectAmount: effectSlider.value
    source: sourceItem
    anchors.fill: sourceItem
    brightness: effectAmount
    colorizationColor: "#ff20d0"
    colorization: effectAmount
    maskEnabled: true
    maskSource: Image {
        source: "mask.png"
    }
    maskSpreadAtMin: 0.2
    maskThresholdMin: effectAmount
    visible: effectAmount < 1.0
}
Slider {
    id: effectSlider
    anchors.bottom: parent.bottom
    anchors.horizontalCenter: parent.horizontalCenter
}

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 visible en «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.

Imágenes borrosas en las que se compara el valor «true» de autoPaddingEnabled, con espacio adicional, frente al valor «false», con bordes recortados

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.

Dos logotipos de Qt con sombras en los que se comparan los valores de `paddingRect`, mostrando una sombra recortada cuando el valor es cero frente a una sombra completa cuando se aplica el relleno.

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.