MultiEffect QML Type
Applique un effet de post-traitement à un élément. Plus d'informations...
| Import Statement: | import QtQuick.Effects |
| Inherits: |
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
Description détaillée
Le type MultiEffect, qui succède au module Qt Graphical Effects, obsolète depuis Qt 5, applique un effet de post-traitement à l'élément source. Par rapport au module Qt Graphical Effects, MultiEffect combine plusieurs effets (flou, ombre, colorisation, etc.) en un seul élément et un seul shader, ce qui le rend plus adapté à des effets multiples. Il existe plusieurs variantes de shaders et la plus optimale est sélectionnée en fonction des fonctionnalités utilisées.
MultiEffect est conçu spécifiquement pour les effets les plus courants et peut être facilement animé. Si le 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: falsepour 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: 0pour l'élément source. Dans ce cas, l'élément source est complètement transparent, mais il 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 propriété est définie sur true (par défaut), la taille de l'élément est automatiquement complétée sur la base 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 également 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 (aucun changement). La quantité de flou total est affectée par blurMax et blurMultiplier.
Remarque concernant les performances : si vous n'avez pas besoin de vous rapprocher de 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 que le flou avec une valeur de 1,0 atteindra.
La plage significative de 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.
Remarque : cette propriété s'applique aux effets de flou et d'ombre.
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 permet d'étendre 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 : Ceci affecte à la fois les effets de flou et d'ombre.
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 le degré de colorisation de la source à l'aide de la fonction colorizationColor.
La valeur est comprise entre 0.0 (pas de coloration) et 1.0 (coloration complète). Par défaut, la propriété est définie sur 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 également 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 |
Accès en lecture seule au nom de fichier du fragment shader actuellement utilisé.
hasProxySource : bool |
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 |
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 |
Au lieu de masquer le contenu situé à l'extérieur de maskThresholdMin et maskThresholdMax, le contenu situé entre les deux 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 l'adresse layer.enabled est 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é du site maskThresholdMin. Le fait de définir 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 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 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 |
Elle permet d'augmenter manuellement la taille de l'élément pour 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 est comprise entre -1.0 (totalement désaturé) et 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.
Remarque : lorsque vous éloignez la position de l'ombre du centre et que vous ajoutez shadowBlur, il est possible que vous deviez également augmenter paddingRect en conséquence si vous voulez que l'ombre ne soit pas écrêté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 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.
Remarque : lorsque vous augmentez l'échelle de l'ombre, il est possible que vous deviez également augmenter la valeur de paddingRect afin d'éviter que l'ombre ne soit coupé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 éloignez la position de l'ombre du centre et que vous ajoutez shadowBlur, il est possible que vous deviez également augmenter paddingRect en conséquence si vous souhaitez que l'ombre ne soit pas écrêtée.
source : Item |
Cette propriété contient l'élément à utiliser comme source pour l'effet. Si nécessaire, MultiEffect générera en interne une ShaderEffectSource comme source de texture.
Remarque : il n'est pas possible de laisser l'effet s'inclure lui-même, par exemple en définissant la source sur le parent de l'effet.
Remarque : si l'élément source a la valeur layer.enabled fixée à true, il sera utilisé directement. C'est une bonne chose pour les performances et c'est souvent ce que l'on souhaite lorsque la source est cachée. Mais si la source reste visible et que l'effet ajoute du rembourrage (autoPaddingEnabled, paddingRect), ce rembourrage peut affecter l'apparence de l'élément source.
Voir également hasProxySource.
vertexShader : string |
Accès en lecture seule au nom de fichier du vertex shader actuellement utilisé.
Signal Documentation
shaderChanged() |
Ce signal est émis lorsque le nuanceur utilisé change.
Remarque : le gestionnaire correspondant est onShaderChanged.
Voir également fragmentShader et vertexShader.
© 2025 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.


