Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

MultiEffect QML Type

Applique un effet de post-traitement à un élément. En savoir plus…

Import Statement: import QtQuick.Effects
Inherits:

Item

Propriétés

Signaux

Description détaillée

Le type MultiEffect, qui succède au 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.) au sein d’un même élément et d’un même shader. Vous pouvez utiliser MultiEffect si vous n’avez besoin que d’un seul effet sans surcoût, mais vous pouvez également l’utiliser pour appliquer plusieurs effets à un élément sans avoir à effectuer plusieurs passes de rendu.

MultiEffect est spécialement conçu 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 l’outil Effect Maker deQt Quick . Pour plus d’informations sur les effets de shader, consultez la documentation de référence sur les shaders ( ShaderEffect ).

Notez que le type MultiEffect 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 MultiEffect à la position de l’élément source. Si l’élément source et l’élément MultiEffect ne sont pas opaques, les deux éléments peuvent être visibles, ce qui peut vous empêcher d’obtenir l’effet souhaité. Pour masquer l’élément source, procédez de l’une des manières suivantes :

  • Définissez la propriété « visible: false » de l’élément source. Dans ce cas, l’élément source n’est pas affiché et ne peut pas recevoir d’entrée tactile ou de clic.
  • Définissez l’ opacity: 0 e de l’élément source. Dans ce cas, l’élément source est entièrement transparent, mais peut toujours recevoir des entrées tactiles ou des clics.

Exemple d’utilisation

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

Logo Qt en niveaux de gris illustrant l'effet de désaturation totale

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

Logo Qt en niveaux de gris illustrant l'effet de désaturation totale

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 simultanément :

Logo Qt avec une lueur verte illustrant à la fois la luminosité, la saturation et des effets de flou combinés

import QtQuick
import QtQuick.Effects

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

Vous trouverez ci-dessous un exemple illustrant comment utiliser conjointement les effets de masque, de colorisation et de luminosité pour faire disparaître progressivement un élément. Ce type de masquage/affichage d’éléments peut, par exemple, être lié à la valeur d’un curseur ou à des animations telles que NumberAnimation. Notez que la propriété visible est définie sur « false » lorsque l’élément est totalement masqué, afin d’éviter un rendu inutile de l’effet.

Quatre étapes de la disparition progressive du logo Qt avec masque et colorisation, passant d'un vert visible à des particules roses qui se dissolvent

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 points à prendre en compte pour optimiser les performances :

  • Pour obtenir le shader le plus optimal, n’activez que les effets que vous utilisez réellement (voir blurEnabled, shadowEnabled, maskEnabled). Les effets de couleur simples (brightness, contrast, saturation, colorization) sont toujours activés ; leur utilisation n’entraîne donc pas de surcharge supplémentaire.
  • Consultez les remarques sur les performances des propriétés susceptibles de modifier la taille du shader ou de l’élément d’effet, et ne les modifiez pas pendant les animations.
  • Lorsque vous n’utilisez pas MultiEffect, pensez à définir sa propriété « visible » sur « false » pour éviter le rendu des effets en arrière-plan.
  • Le flou et les ombres sont les effets les plus gourmands en ressources. Dans ce cas, privilégiez l’augmentation de la valeur « blurMultiplier » plutôt que celle de « blurMax » et évitez d’utiliser des éléments « source » qui s’animent, afin que le flou n’ait pas besoin d’être régénéré à chaque image.
  • Appliquez les effets à des éléments QML de taille optimale, car plus il y a de pixels, plus la charge de travail du GPU est importante. Lorsque vous appliquez l’effet de flou à l’ensemble de l’arrière-plan, n’oubliez pas de définir autoPaddingEnabled sur false, sinon l’effet s’étendra « au-delà » de la fenêtre ou de l’écran.

Vous pouvez combiner la propriété ShaderEffectSource et la propriété MultiEffect:

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

Documentation des propriétés

autoPaddingEnabled : bool

Lorsque les effets de flou ou d’ombre sont activés et que cette option est définie sur « true » (valeur par défaut), la taille de l’élément est automatiquement complétée en fonction des valeurs indiquées sur blurMax et blurMultiplier. Notez que la valeur paddingRect est toujours ajoutée à la taille.

Images floues comparant le paramètre `autoPaddingEnabled` défini sur `true` (avec un espace supplémentaire) et sur `false` (avec des bords rognés)

Remarque concernant les performances : la taille de l'élément doit être aussi petite que possible pour des performances optimales.

Remarque concernant les performances : cela entraîne un redimensionnement de l'élément ; ne modifiez pas cette propriété pendant une animation.

Voir également paddingRect.

blur : real

Cette propriété définit l'intensité du flou (rayon) appliqué à la source.

La valeur varie de 0,0 (pas de flou) à 1,0 (flou maximal). Par défaut, la propriété est définie sur 0.0 (aucun changement). L'intensité du flou maximal dépend des paramètres blurMax et blurMultiplier.

Remarque concernant les performances : si vous n’avez pas besoin d’atteindre une valeur proche de 1,0 à aucun moment des animations de flou, envisagez de réduire les valeurs de « blurMax » ou « blurMultiplier » pour optimiser les performances.

blurEnabled : bool

Active l'effet de flou.

Remarque concernant les performances : entraîne un changement de shader ; ne modifiez pas cette propriété pendant une animation.

blurMax : int

Cette propriété définit le rayon maximal en pixels que le flou avec une valeur de 1,0 peut atteindre.

La plage significative de cette valeur va de 2 (flou subtil) à 64 (flou important). Par défaut, la propriété est définie sur 32. Pour des performances optimales, choisissez la valeur la plus faible possible.

Remarque : cela affecte à la fois les effets de flou et d’ombre.

Remarque concernant les performances : entraîne une modification du shader ; ne modifiez pas cette propriété pendant une animation.

Remarque concernant 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 de 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. Augmenter le multiplicateur agrandit le rayon de flou, mais réduit la qualité du flou. Cette option est plus performante pour un rayon de flou plus grand que blurMax, car elle n'augmente pas le nombre de recherches de textures.

Remarque : cela affecte à la fois les effets de flou et d’ombre.

Remarque concernant les performances : cela entraîne un redimensionnement de l’élément ; ne modifiez pas cette propriété pendant une 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 le degré de colorisation de la source à l'aide de l'colorizationColor.

La valeur varie de 0,0 (pas de colorisation) à 1,0 (colorisation complète). Par défaut, la propriété est définie sur « 0.0 » (aucun changement).

colorizationColor : color

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

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

Voir également colorization.

contrast : real

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

Sa 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 du fichier du shader de fragment actuellement utilisé.

hasProxySource : bool [read-only]

Renvoie « true » lorsque l'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. Cela peut servir, par exemple, à visualiser la zone couverte par l'élément.

Voir également paddingRect et autoPaddingEnabled.

maskEnabled : bool

Active l'effet de masque.

Remarque concernant les performances : entraîne un changement de shader ; ne modifiez pas cette propriété pendant une animation.

maskInverted : bool

Cette propriété inverse le masque : au lieu de masquer le contenu situé en dehors de maskThresholdMin et maskThresholdMax, c'est le contenu situé entre ces deux adresses qui sera masqué.

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

maskSource : Item

Élément source pour l'effet de masque. Doit pointer vers ShaderEffectSource, vers un élément dont le paramètre « layer.enabled » est défini sur true, ou vers un élément pouvant être utilisé directement comme source de texture (par exemple, Image). Le canal alpha de l'élément source est utilisé pour le masquage.

Si « maskSource » et la source ont des dimensions différentes, l’image « maskSource » est étirée pour s’adapter à la taille de la source.

maskSpreadAtMax : real

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

La valeur varie de 0,0 (bord de masque net) à 1,0 (bord de masque lissé). 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 l'maskThresholdMin. La définition de valeurs d'étalement plus élevées adoucit la transition entre les pixels transparents et les pixels opaques du masque en ajoutant des valeurs interpolées entre eux.

La valeur varie de 0,0 (bord net du masque) à 1,0 (bord lissé du masque). Par défaut, cette 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 du masque dont la valeur alpha est inférieure à cette propriété sont utilisés pour masquer entièrement les pixels correspondants de l'élément source. Les pixels du masque dont la valeur alpha est supérieure sont utilisés pour effectuer un mélange alpha de l'élément source à l'affichage.

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 du masque dont la valeur alpha est inférieure à cette propriété sont utilisés pour masquer entièrement les pixels correspondants de l'élément source. Les pixels du masque dont la valeur alpha est supérieure sont utilisés pour effectuer un mélange alpha entre l'élément source et l'affichage.

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

Définissez ce paramètre pour augmenter manuellement la taille de l'élément afin que le flou et/ou les ombres s'y adaptent correctement. Si la valeur de « autoPaddingEnabled » est « true » et que « paddingRect » n'est pas défini, l'élément est agrandi pour s'adapter à l'élément présentant le flou maximal, conformément aux propriétés « blurMax » et « blurMultiplier ». Lorsque vous activez l'ombre, vous devez généralement tenir compte des propriétés « shadowHorizontalOffset » et « shadowVerticalOffset » et ajuster « paddingRect » en conséquence.

Vous trouverez ci-dessous un exemple d’ajustement de `paddingRect` avec ` autoPaddingEnabled ` défini sur `false`, afin que l’ombre s’insère à l’intérieur de l’élément MultiEffect.

Deux logos Qt avec des ombres, comparant les valeurs de `paddingRect` : l'un présente une ombre tronquée lorsque la valeur est nulle, tandis que l'autre affiche une ombre complète grâce au `padding`.

Remarque concernant les performances : la taille de l’élément doit être aussi petite que possible pour des performances optimales.

Remarque concernant les performances : entraîne un redimensionnement de l’élément ; ne modifiez pas cette propriété pendant une 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 varie 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 l'intensité du flou (rayon) appliqué à l'ombre.

La valeur varie de 0,0 (pas de flou) à 1,0 (flou maximal). Par défaut, la propriété est définie sur 1.0. L'intensité du flou maximal dépend des paramètres blurMax et blurMultiplier.

Remarque concernant les performances : la meilleure façon de réduire le flou des ombres est de réduire la valeur de ` blurMax ` (si cela n’est pas nécessaire pour le flou des éléments). Veillez simplement à ne pas modifier ` blurMax ` pendant les animations.

shadowColor : color

Cette propriété définit la valeur de 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, cette propriété est définie sur « Qt.rgba(0.0, 0.0, 0.0, 1.0) » (noir).

shadowEnabled : bool

Active l'effet d'ombre.

Remarque concernant les performances : entraîne un changement de shader ; ne modifiez pas cette propriété pendant une 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.

Remarque : lorsque vous déplacez la position de l'ombre loin du centre et que vous ajoutez « shadowBlur », vous devrez peut-être également augmenter la valeur de « paddingRect » en conséquence si vous souhaitez que l'ombre ne soit pas tronquée.

shadowOpacity : real

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

La valeur est comprise entre 0,0 (entièrement transparent) et 1,0 (entièrement 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.

Remarque : lorsque vous augmentez la valeur de shadowScale, vous devrez peut-être également augmenter la valeur de paddingRect en conséquence pour éviter que l'ombre ne soit tronquée.

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.

Remarque : lorsque vous déplacez la position de l'ombre hors du centre et que vous ajoutez « shadowBlur », vous devrez peut-être également augmenter la valeur « paddingRect » en conséquence si vous souhaitez que l'ombre ne soit pas tronquée.

source : Item

Cette propriété contient l'élément qui servira de source à l'effet. Si nécessaire, MultiEffect générera en interne un « ShaderEffectSource » (élément de texture) comme source de texture.

Remarque : il n’est pas pris en charge de faire en sorte que l’effet s’inclue lui-même, par exemple en définissant la source sur le parent de l’effet.

Remarque : si l'élément source a la propriété « layer.enabled » définie sur « true », il sera utilisé directement. Cela est bénéfique pour les performances et souvent souhaitable lorsque la source est masquée. Cependant, si la source reste visible et que l’effet ajoute un remplissage (autoPaddingEnabled, paddingRect), ce remplissage peut affecter l’apparence de l’élément source.

Voir également hasProxySource.

vertexShader : string [read-only]

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

Documentation sur les signaux

shaderChanged()

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

Remarque : le gestionnaire correspondant est onShaderChanged.

Voir également fragmentShader et 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.