MultiEffect QML Type

Applique un effet de post-traitement à un élément. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• 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

Signaux

• shaderChanged()

Description détaillée

Le type MultiEffect, successeur du module Qt Graphical Effects de Qt 5, applique un effet de post-traitement à l'élément source. Contrairement au module Qt Graphical Effects, MultiEffect permet de combiner plusieurs effets (flou, ombre, colorisation, etc.) dans un seul élément et un seul shader. Vous pouvez utiliser MultiEffect si vous n'avez besoin que d'un seul effet sans frais supplémentaires, mais vous pouvez également l'utiliser pour appliquer plusieurs effets à un élément sans le coût de plusieurs passes de rendu.

MultiEffect est conçu spécifiquement pour les effets les plus courants et peut être facilement animé. Si MultiEffect ne contient pas l'effet dont vous avez besoin, envisagez d'implémenter un effet personnalisé à l'aide de Qt Quick Effect Maker. Pour plus d'informations sur les effets de shaders, consultez la documentation de référence ShaderEffect.

Notez que le type MultiEffet rend un nouvel élément visuel à côté de l'élément source. Pour appliquer l'effet à l'élément source, vous devez placer le nouvel élément MultiEffet à la position de l'élément source. Si l'élément source et l'élément MultiEffet ne sont pas opaques, les deux éléments peuvent être visibles, ce qui risque de ne pas produire l'effet désiré. Pour masquer l'élément source, procédez comme suit :

• Définissez visible: false pour l'élément source. Dans ce cas, l'élément source n'est pas rendu du tout et ne peut pas être touché ou cliqué.
• Définissez opacity: 0 pour l'élément source. Dans ce cas, l'élément source est complètement transparent, mais peut toujours être touché ou cliqué.

Exemple d'utilisation

L'exemple suivant montre comment appliquer un effet de saturation à un élément :

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
}

L'exemple suivant montre comment appliquer un effet de saturation à un élément : 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
    }
}

L'exemple suivant montre comment appliquer plusieurs effets en même temps :

import QtQuick
import QtQuick.Effects

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

L'exemple ci-dessous montre comment utiliser conjointement les effets de masque, de colorisation et de luminosité pour faire disparaître un élément. Ce type de masquage/affichage d'éléments peut, par exemple, être lié à une valeur de curseur ou à des animations telles que NumberAnimation. Notez que la propriété visible est fausse lorsque l'élément est totalement effacé, afin d'éviter un rendu inutile de l'effet.

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
}

Performances

Il y a quelques éléments à prendre en compte pour obtenir des performances optimales :

• Pour obtenir le shader le plus optimal, activez uniquement les effets que vous utilisez réellement (voir blurEnabled, shadowEnabled, maskEnabled). Les effets de couleur simples (brightness, contrast, saturation, colorization) sont toujours activés, de sorte que leur utilisation n'entraîne pas de surcharge supplémentaire.
• Consultez les notes de performance des propriétés qui peuvent modifier le shader ou la taille de l'élément d'effet et ne les modifiez pas pendant les animations.
• Lorsque le MultiEffect n'est pas utilisé, n'oubliez pas de définir sa propriété visible à false pour éviter de rendre les effets en arrière-plan.
• Le flou et l'ombre sont les effets les plus lourds. Pour ceux-ci, préférez augmenter blurMultiplier par rapport à blurMax et évitez d'utiliser des éléments source qui s'animent, afin que le flou ne doive pas être régénéré à chaque image.
• Appliquez les effets à des éléments QML de taille optimale, car plus de pixels signifie plus de travail pour le GPU. Lorsque vous appliquez l'effet de flou à l'ensemble de l'arrière-plan, n'oubliez pas de définir autoPaddingEnabled false, sinon l'effet s'étend à l'extérieur de la fenêtre ou de l'écran.

Vous pouvez combiner les éléments ShaderEffectSource et MultiEffect:

• Pour utiliser le même élément source dans plusieurs effets et le garder inchangé.
• Pour utiliser une partie de l'élément source, en utilisant ShaderEffectSource.sourceRect.
• Pour diminuer la résolution de l'élément source, par exemple pour améliorer les performances, en utilisant la propriété ShaderEffectSource.textureSize.

Documentation sur les propriétés

autoPaddingEnabled : bool

Lorsque les effets de flou ou d'ombre sont activés et que cette option est réglée sur true (valeur par défaut), la taille de l'élément est automatiquement complétée en fonction de blurMax et blurMultiplier. Notez que paddingRect est toujours ajouté à la taille.

Note de performance : La taille de l'élément doit être aussi petite que possible pour des performances optimales.

Note sur les performances : entraîne un redimensionnement de l'élément ; ne modifiez pas cette propriété pendant l'animation.

Voir aussi paddingRect.

blur : real

Cette propriété définit le degré de flou (rayon) appliqué à la source.

La valeur est comprise entre 0,0 (pas de flou) et 1,0 (flou total). Par défaut, la propriété est définie sur 0.0 (pas de changement). La quantité de flou total est affectée par blurMax et blurMultiplier.

Remarque concernant les performances : si vous n'avez pas besoin d'approcher 1,0 à tout moment des animations de flou, envisagez de réduire blurMax ou blurMultiplier pour obtenir des performances optimales.

blurEnabled : bool

Active l'effet de flou.

Note sur les performances : entraîne une modification du shader ; ne modifiez pas cette propriété pendant l'animation.

blurMax : int

Cette propriété définit le rayon maximal de pixels qu'un flou de valeur 1.0 atteindra.

Cette valeur est comprise entre 2 (flou subtil) et 64 (flou important). Par défaut, la propriété est définie sur 32. Pour des performances optimales, choisissez une valeur aussi petite que nécessaire.

Note sur les performances : entraîne une modification du shader ; ne modifiez pas cette propriété pendant l'animation.

Note sur les performances : entraîne un redimensionnement de l'élément ; ne modifiez pas cette propriété pendant l'animation.

blurMultiplier : real

Cette propriété définit un multiplicateur permettant d'étendre le rayon du flou.

La valeur est comprise entre 0,0 (pas de multiplication) et inf. Par défaut, la propriété est définie sur 0.0. L'augmentation du multiplicateur étend le rayon de flou, mais diminue la qualité du flou. Pour un rayon de flou plus important, cette option est plus performante que blurMax car elle n'augmente pas le nombre de recherches de textures.

Note sur les performances : entraîne un redimensionnement de l'élément ; ne modifiez pas cette propriété pendant l'animation.

brightness : real

Cette propriété définit dans quelle mesure la luminosité de la source est augmentée ou diminuée.

La valeur est comprise entre -1,0 et 1,0. Par défaut, la propriété est définie sur 0.0 (aucun changement).

colorization : real

Cette propriété définit dans quelle mesure la source est colorisée avec le site colorizationColor.

La valeur est comprise entre 0.0 (pas de coloration) et 1.0 (coloration complète). Par défaut, la propriété est fixée à 0.0 (pas de changement).

colorizationColor : color

Cette propriété définit la valeur de la couleur RGBA utilisée pour coloriser la source.

Par défaut, la propriété est définie sur Qt.rgba(1.0, 0.0, 0.0, 1.0) (rouge).

Voir aussi colorization.

contrast : real

Cette propriété définit dans quelle mesure le contraste de la source est augmenté ou diminué.

La valeur est comprise entre -1,0 et 1,0. Par défaut, la propriété est définie sur 0.0 (aucun changement).

fragmentShader : string [read-only]

Accès en lecture seule au nom de fichier du nuanceur de fragment actuellement utilisé.

hasProxySource : bool [read-only]

Retourne true lorsque MultiEffect crée en interne ShaderEffectSource pour l'élément source et false lorsque l'élément source est utilisé tel quel. Par exemple, lorsque la source est l'élément Image ou Item avec layer.enabled défini sur true, cette source proxy supplémentaire n'est pas nécessaire.

itemRect : rect [read-only]

Accès en lecture seule au rectangle de l'élément d'effet. Il peut être utilisé, par exemple, pour voir la zone couverte par l'élément.

Voir également paddingRect et autoPaddingEnabled.

maskEnabled : bool

Active l'effet de masque.

Note sur les performances : entraîne une modification du shader ; ne modifiez pas cette propriété pendant l'animation.

maskInverted : bool

Cette propriété fait passer le masque du côté opposé ; au lieu de masquer le contenu à l'extérieur de maskThresholdMin et maskThresholdMax, le contenu entre ces deux sites sera masqué.

Par défaut, la propriété est définie sur false.

maskSource : Item

Élément source de l'effet de masque. Il doit pointer sur ShaderEffectSource, sur un élément dont la valeur layer.enabled est réglée sur true, ou sur un élément qui peut être directement utilisé comme source de texture (par exemple, Image). Le canal alpha de l'élément source est utilisé pour le masquage.

Si la source du masque et la source ont des dimensions différentes, l'image de la source du masque est étirée pour correspondre à la taille de la source.

maskSpreadAtMax : real

Cette propriété définit la douceur des bords du masque à proximité de maskThresholdMax. L'utilisation de valeurs d'étalement plus élevées adoucit la transition entre les pixels transparents du masque et les pixels opaques du masque en ajoutant des valeurs interpolées entre eux.

La valeur est comprise entre 0,0 (bord de masque net) et 1,0 (bord de masque lisse). Par défaut, la propriété est définie sur 0.0.

maskSpreadAtMin : real

Cette propriété définit la douceur des bords du masque à proximité de maskThresholdMin. Le fait de fixer des valeurs d'étalement plus élevées adoucit la transition entre les pixels transparents du masque et les pixels opaques du masque en ajoutant des valeurs interpolées entre eux.

La valeur est comprise entre 0,0 (bord de masque net) et 1,0 (bord de masque lisse). Par défaut, la propriété est définie sur 0.0.

maskThresholdMax : real

Cette propriété définit une valeur seuil supérieure pour les pixels du masque. Les pixels de masque dont la valeur alpha est inférieure à cette propriété sont utilisés pour masquer complètement les pixels correspondants de l'élément source. Les pixels du masque qui ont une valeur alpha supérieure sont utilisés pour afficher l'élément source à l'écran.

La valeur est comprise entre 0,0 (valeur alpha 0) et 1,0 (valeur alpha 255). Par défaut, la propriété est définie sur 1.0.

maskThresholdMin : real

Cette propriété définit une valeur seuil inférieure pour les pixels du masque. Les pixels de masque dont la valeur alpha est inférieure à cette propriété sont utilisés pour masquer complètement les pixels correspondants de l'élément source. Les pixels du masque dont la valeur alpha est supérieure sont utilisés pour afficher l'élément source à l'écran.

La valeur est comprise entre 0,0 (valeur alpha 0) et 1,0 (valeur alpha 255). Par défaut, la propriété est définie sur 0.0.

paddingRect : rect

Ce paramètre permet d'augmenter manuellement la taille de l'élément de manière à ce que le flou et/ou les ombres s'adaptent. Si autoPaddingEnabled est vrai et que paddingRect n'est pas défini, l'élément est agrandi pour s'adapter à l'élément le plus flou possible, sur la base de blurMax et blurMultiplier. Lorsque vous activez l'ombre, vous devez généralement tenir compte de shadowHorizontalOffset et shadowVerticalOffset et ajuster le paddingRect en conséquence.

Vous trouverez ci-dessous un exemple d'ajustement de paddingRect avec autoPaddingEnabled réglé sur false de manière à ce que l'ombre s'adapte à l'intérieur de l'élément MultiEffect.

Note de performance : La taille de l'élément doit être aussi petite que possible pour des performances optimales.

Note sur les performances : entraîne un redimensionnement de l'élément ; ne modifiez pas cette propriété pendant l'animation.

Voir également autoPaddingEnabled.

saturation : real

Cette propriété définit dans quelle mesure la saturation de la source est augmentée ou diminuée.

La valeur va de -1.0 (totalement désaturé) à inf. Par défaut, la propriété est définie sur 0.0 (aucun changement).

shadowBlur : real

Cette propriété définit le degré de flou (rayon) appliqué à l'ombre.

La valeur est comprise entre 0,0 (pas de flou) et 1,0 (flou total). Par défaut, la propriété est définie sur 1.0. La quantité de flou total est affectée par blurMax et blurMultiplier.

Note sur les performances : la meilleure façon de réduire le flou des ombres est de réduire la taille de blurMax (si elle n'est pas nécessaire pour le flou de l'élément). N'oubliez pas de ne pas ajuster blurMax pendant les animations.

shadowColor : color

Cette propriété définit la valeur de la couleur RGBA utilisée pour l'ombre. Elle est utile, par exemple, lorsqu'une ombre est utilisée pour simuler un effet de lueur.

Par défaut, la propriété est définie sur Qt.rgba(0.0, 0.0, 0.0, 1.0) (noir).

shadowEnabled : bool

Active l'effet d'ombre.

Note sur les performances : entraîne une modification du shader ; ne modifiez pas cette propriété pendant l'animation.

shadowHorizontalOffset : real

Cette propriété définit le décalage horizontal de l'ombre par rapport au centre de l'élément.

La valeur est comprise entre -inf et inf. Par défaut, la propriété est définie sur 0.0.

shadowOpacity : real

Cette propriété définit l'opacité de l'ombre portée. Cette valeur est multipliée par la valeur alpha de shadowColor.

La valeur est comprise entre 0,0 (totalement transparent) et 1,0 (totalement opaque). Par défaut, la propriété est définie sur 1.0.

shadowScale : real

Cette propriété définit l'échelle de l'ombre. L'échelle est appliquée à partir du centre de l'élément.

La valeur est comprise entre 0 et inf. Par défaut, la propriété est définie sur 1.0.

shadowVerticalOffset : real

Cette propriété définit le décalage vertical de l'ombre par rapport au centre de l'élément.

La valeur est comprise entre -inf et inf. Par défaut, la propriété est définie sur 0.0.

source : Item

Cette propriété contient l'élément à utiliser comme source pour l'effet. Si nécessaire, MultiEffect génère en interne un ShaderEffectSource comme source de texture.

Voir également hasProxySource.

vertexShader : string [read-only]

Accès en lecture seule au nom de fichier du vertex shader actuellement utilisé.

Documentation sur les signaux

shaderChanged()

Ce signal est émis lorsque le shader utilisé change.

Voir également fragmentShader et vertexShader.