MultiEffect QML Type

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

• Lista de todos los miembros, incluidos los heredados

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

• shaderChanged()

Descripción detallada

El tipo MultiEffect, sucesor del Qt Graphical Effects de Qt 5, aplica un efecto de post-procesado al elemento source. A diferencia del módulo Qt Graphical Effects, MultiEffect permite combinar múltiples efectos (desenfoque, sombra, coloración, etc.) en un único elemento y sombreador. Puede utilizar MultiEffect si sólo necesita un único efecto sin sobrecarga adicional, pero también puede utilizarlo para aplicar múltiples efectos a un elemento sin el coste de múltiples pases de renderizado.

MultiEffect está diseñado específicamente para los efectos más comunes y se puede animar fácilmente. Si el MultiEffect no contiene el efecto que necesita, considere implementar un efecto personalizado utilizando Qt Quick Effect Maker. Para obtener más información sobre los efectos de sombreado, consulte la documentación de referencia de ShaderEffect.

Ten en cuenta que el tipo MultiEffect renderiza un nuevo elemento visual junto al elemento fuente. Para aplicar el efecto al elemento fuente, debes colocar el nuevo elemento MultiEffect en la posición del elemento fuente. Si el elemento fuente y el elemento MultiEfecto no son opacos, ambos elementos pueden ser visibles, por lo que es posible que no obtengas el efecto deseado. Para ocultar el elemento fuente, realice una de las siguientes acciones:

• Configure visible: false para el elemento fuente. En este caso, el elemento de origen no se muestra y no puede recibir pulsaciones.
• Defina opacity: 0 para el elemento fuente. En este caso, el elemento fuente es completamente transparente, pero puede recibir pulsaciones.

Ejemplo de uso

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

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 layered Item:

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 múltiples efectos al mismo tiempo:

import QtQuick
import QtQuick.Effects

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

El siguiente ejemplo muestra cómo utilizar conjuntamente los efectos de máscara, coloración y brillo para ocultar/mostrar un elemento. Este tipo de ocultar/mostrar elementos puede ser, por ejemplo, vinculado a un valor deslizante o animaciones como NumberAnimation. Observe cómo la propiedad visible es falsa cuando el elemento está totalmente desvanecido, para evitar el renderizado innecesario del efecto.

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 algunas cosas a tener en cuenta para un rendimiento óptimo:

• Para obtener el shader más óptimo, active sólo los efectos que realmente utilice (ver blurEnabled, shadowEnabled, maskEnabled). Los efectos de color simples (brightness, contrast, saturation, colorization) están siempre habilitados, por lo que su uso no añade sobrecarga adicional.
• Consulte las notas de rendimiento de las propiedades que pueden cambiar el sombreador o el tamaño del elemento del efecto y no las modifique durante las animaciones.
• Cuando no se utilice el MultiEffect, recuerda establecer su propiedad visible a false para evitar renderizar los efectos en segundo plano.
• El desenfoque y la sombra son los efectos más pesados. Con ellos, prefiera aumentar blurMultiplier sobre blurMax y evite usar elementos source que se animan, para que el desenfoque no tenga que regenerarse en cada fotograma.
• Aplica los efectos a elementos QML de tamaño óptimo, ya que más píxeles significan más trabajo para la GPU. Cuando apliques el efecto de desenfoque a todo el fondo, recuerda configurar autoPaddingEnabled false o el efecto crecerá "fuera" de la ventana / pantalla.

Puede combinar el ShaderEffectSource y el MultiEffect:

• Para utilizar el mismo elemento fuente en múltiples efectos y mantenerlo sin cambios.
• Para utilizar una parte del elemento fuente, utilizando ShaderEffectSource.sourceRect.
• Para disminuir la resolución del elemento fuente, por ejemplo, para mejorar el rendimiento, utilizando la propiedad ShaderEffectSource.textureSize.

Documentación de propiedades

autoPaddingEnabled : bool

Cuando los efectos de desenfoque o sombra están activados y este valor es verdadero (por defecto), el tamaño del elemento se rellena automáticamente en función de blurMax y blurMultiplier. Tenga en cuenta que paddingRect siempre se añade al tamaño.

Nota de rendimiento: el tamaño del elemento debe ser lo más pequeño posible para un rendimiento óptimo.

Nota de rendimiento: Provoca un cambio de tamaño del elemento; no modifique esta propiedad durante la animación.

Véase también paddingRect.

blur : real

Esta propiedad define cuánto desenfoque (radio) se aplica a la fuente.

El valor oscila entre 0.0 (sin desenfoque) y 1.0 (desenfoque completo). Por defecto, la propiedad está establecida en 0.0 (sin cambios). La cantidad de desenfoque total se ve afectada por blurMax y blurMultiplier.

Nota de rendimiento: Si no necesita acercarse a 1.0 en ningún punto de las animaciones de desenfoque, considere reducir blurMax o blurMultiplier para obtener un rendimiento óptimo.

blurEnabled : bool

Activa el efecto de desenfoque.

Nota de rendimiento: Provoca un cambio de sombreado; no modifique esta propiedad durante la animación.

blurMax : int

Esta propiedad define el radio máximo de píxeles que alcanzará el desenfoque con valor 1.0.

El rango significativo de este valor va de 2 (desenfoque sutil) a 64 (desenfoque alto). Por defecto, la propiedad está establecida en 32. Para un rendimiento óptimo, seleccione un valor tan pequeño como necesite.

Nota de rendimiento: Provoca un cambio de shader; no modifique esta propiedad durante la animación.

Nota de 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 va de 0.0 (no multiplicado) a inf. Por defecto, la propiedad está establecida en 0.0. Aumentar el multiplicador amplía el radio de desenfoque, pero disminuye la calidad del desenfoque. Esta opción es más eficaz para un radio de desenfoque mayor que blurMax, ya que no aumenta la cantidad de búsquedas de texturas.

Nota de rendimiento: Provoca un cambio de tamaño del elemento; no cambie esta propiedad durante la animación.

brightness : real

Esta propiedad define cuánto aumenta o disminuye el brillo de la fuente.

El valor oscila entre -1,0 y 1,0. Por defecto, la propiedad está establecida en 0.0 (sin cambios).

colorization : real

Esta propiedad define cuánto se colorea la fuente con colorizationColor.

El valor oscila entre 0,0 (no coloreada) y 1,0 (totalmente coloreada). 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 colorear la fuente.

Por defecto, la propiedad se establece en Qt.rgba(1.0, 0.0, 0.0, 1.0) (rojo).

Véase también colorization.

contrast : real

Esta propiedad define cuánto aumenta o disminuye el contraste de la fuente.

El valor oscila entre -1,0 y 1,0. Por defecto, la propiedad está establecida en 0.0 (sin cambios).

fragmentShader : string [read-only]

Acceso de sólo lectura al nombre de archivo del fragment shader utilizado actualmente.

hasProxySource : bool [read-only]

Devuelve true cuando MultiEffect crea internamente ShaderEffectSource para el elemento source y false cuando el elemento source se utiliza tal cual. Por ejemplo, cuando la fuente es el elemento Image o Item con layer.enabled establecido en true, esta fuente proxy adicional no es necesaria.

itemRect : rect [read-only]

Acceso de sólo lectura al rectángulo del elemento de efecto. Se puede utilizar, 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 de rendimiento: Provoca un cambio de sombreado; no modifique esta propiedad durante la animación.

maskInverted : bool

Esta propiedad cambia la máscara al lado opuesto; en lugar de enmascarar el contenido fuera de maskThresholdMin y maskThresholdMax, se enmascarará el contenido entre ellos.

Por defecto, la propiedad está establecida en false.

maskSource : Item

Elemento fuente para el efecto de máscara. Debe apuntar a ShaderEffectSource, ítem con layer.enabled ajustado a true, o a un ítem que pueda ser usado directamente como fuente de textura (por ejemplo, Image). El canal alfa del elemento fuente se utiliza para el enmascaramiento.

Si el maskSource y la fuente tienen dimensiones diferentes, la imagen maskSource se estira para que coincida con el tamaño de la fuente.

maskSpreadAtMax : real

Esta propiedad define la suavidad de los bordes de la máscara cerca de maskThresholdMax. El uso de valores de dispersión más altos suaviza la transición de los píxeles transparentes de la máscara hacia los píxeles opacos de la máscara 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). Por defecto, la propiedad está establecida en 0.0.

maskSpreadAtMin : real

Esta propiedad define la suavidad de los bordes de la máscara cerca de maskThresholdMin. Si se establecen 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 de la máscara 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). Por defecto, la propiedad está establecida en 0.0.

maskThresholdMax : real

Esta propiedad define un valor de umbral superior para los píxeles de la máscara. Los píxeles de máscara que tienen un valor alfa inferior a esta propiedad se utilizan para enmascarar completamente los píxeles correspondientes del elemento fuente. Los píxeles de la máscara que tienen un valor alfa superior se utilizan para alfabatear el elemento fuente en la pantalla.

El valor oscila entre 0.0 (valor alfa 0) y 1.0 (valor alfa 255). Por defecto, la propiedad está establecida en 1.0.

maskThresholdMin : real

Esta propiedad define un valor de umbral inferior para los píxeles de máscara. Los píxeles de máscara que tienen un valor alfa inferior a esta propiedad se utilizan para enmascarar completamente los píxeles correspondientes del elemento fuente. Los píxeles de la máscara que tienen un valor alfa más alto se utilizan para alfabatear el elemento fuente en la pantalla.

El valor oscila entre 0.0 (valor alfa 0) y 1.0 (valor alfa 255). Por defecto, la propiedad está establecida en 0.0.

paddingRect : rect

Establézcalo para aumentar manualmente el tamaño del elemento para que quepan el desenfoque y/o las sombras. Si autoPaddingEnabled es verdadero y paddingRect no está establecido, el elemento se rellena para que quepa el máximo desenfoque basado en blurMax y blurMultiplier. Cuando se activa la sombra, normalmente es necesario tener en cuenta shadowHorizontalOffset y shadowVerticalOffset y ajustar este paddingRect en consecuencia.

A continuación se muestra un ejemplo de ajuste de paddingRect con autoPaddingEnabled establecido en false para que la sombra quepa dentro del elemento MultiEffect.

Nota de rendimiento: El tamaño del elemento debe ser lo más pequeño posible para un rendimiento óptimo.

Nota de 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 cuánto aumenta o disminuye la saturación de la fuente.

El valor va de -1.0 (totalmente desaturado) a inf. Por defecto, la propiedad está establecida en 0.0 (sin cambios).

shadowBlur : real

Esta propiedad define cuánto desenfoque (radio) se aplica a la sombra.

El valor oscila entre 0.0 (sin desenfoque) y 1.0 (desenfoque completo). Por defecto, la propiedad está establecida en 1.0. La cantidad de desenfoque total se ve afectada por blurMax y blurMultiplier.

Nota de rendimiento: La forma más óptima de reducir el desenfoque de las sombras es hacer blurMax más pequeño (si no es necesario para el desenfoque de los elementos). Recuerda no ajustar blurMax durante las animaciones.

shadowColor : color

Esta propiedad define el valor de color RGBA que se utiliza para la sombra. Es útil, por ejemplo, cuando se utiliza una sombra para simular un efecto de resplandor.

Por defecto, la propiedad se establece en Qt.rgba(0.0, 0.0, 0.0, 1.0) (negro).

shadowEnabled : bool

Activa el efecto de sombra.

Nota de rendimiento: Provoca el cambio del sombreador; no modifique esta propiedad durante la animación.

shadowHorizontalOffset : real

Esta propiedad define el desplazamiento horizontal de la sombra desde el centro del elemento.

El valor oscila entre -inf e inf. Por defecto, la propiedad está establecida en 0.0.

shadowOpacity : real

Esta propiedad define la opacidad de la sombra paralela. 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 va de 0 a inf. Por defecto, la propiedad está establecida en 1.0.

shadowVerticalOffset : real

Esta propiedad define el desplazamiento vertical de la sombra desde el centro del elemento.

El valor oscila entre -inf e inf. Por defecto, la propiedad está establecida en 0.0.

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.

Véase también hasProxySource.

vertexShader : string [read-only]

Acceso de sólo lectura al nombre de archivo del sombreador de vértices utilizado actualmente.

Documentación de señales

shaderChanged()

Esta señal se emite cuando cambia el sombreador utilizado.

Véase también fragmentShader y vertexShader.