Back to Qt.io
Contact Us Blog Download Qt

MultiEffect QML Type

对项目应用后处理效果。更多

Import Statement: import QtQuick.Effects
Inherits:

Item

属性

信号

详细说明

MultiEffect 类型是 Qt 5 中已废弃的 QtGraphical Effects 的后继类型，可对source 项目应用后处理效果。与 QtGraphical Effects 模块相比，MultiEffect 将多种效果（模糊、阴影、着色等）合并到一个项目和着色器中，这使其更适合多种效果。着色器有多种变体，可根据使用的功能选择最合适的着色器。

MultiEffect 专为最常见的效果而设计，可以轻松制作动画。如果 MultiEffect 不包含您需要的特效，可以考虑使用 Qt Quick Effect Maker.有关着色器效果的更多信息，请参阅ShaderEffect 参考文档。

请注意，MultiEffect 类型会在源项目旁边渲染一个新的可视化项目。要将效果应用到源项目，需要将新的 MultiEffect 项目放在源项目的位置上。如果源项目和多重效果项目不是不透明的，那么这两个项目都可能是可见的，因此可能无法获得理想的效果。要隐藏源项目，请执行以下操作：

  • 为源项目设置visible: false 。在这种情况下，源项目根本不会呈现，也不会接收触摸或点击输入。
  • 为源项目设置opacity: 0 。在这种情况下，源项目完全透明，但仍可接收触摸或点击输入。

使用示例

下面的示例显示了如何对项目应用饱和效果：

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
}

下面的示例显示了如何对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
    }
}

下面的示例显示了如何同时应用多种效果：

import QtQuick
import QtQuick.Effects

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

下面的示例说明了如何同时使用遮罩、着色和亮度效果来淡化一个元素。例如，这种元素的隐藏/显示可以与滑块值或动画（如NumberAnimation ）绑定。请注意，当项目完全消隐时，visible 属性为 false，以避免不必要的效果渲染。

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
}

性能

要获得最佳性能，有几件事需要考虑：

  • 为获得最佳着色器效果，请仅启用实际使用的效果（请参阅blurEnabled,shadowEnabled,maskEnabled ）。简单的色彩效果 (brightness,contrast,saturation,colorization) 始终处于启用状态，因此使用它们不会增加额外的开销。
  • 请参阅可能会改变着色器或效果项大小的属性的性能说明，并且不要在动画期间修改这些属性。
  • 在不使用多重效果时，请记住将其visible 属性设置为 false，以避免在后台渲染效果。
  • 模糊和阴影是最重的效果。在使用这些效果时，最好增加blurMultiplier 而不是blurMax ，并避免使用会产生动画的source 项目，这样模糊效果就不需要在每一帧中重新生成。
  • 将特效应用于最佳尺寸的 QML 元素，因为像素越多意味着 GPU 的工作量越大。在对整个背景应用模糊效果时，请记住将autoPaddingEnabled 设置为 false，否则效果会 "超出 "窗口/屏幕。

您可以将ShaderEffectSource 和MultiEffect 结合使用：

属性文档

autoPaddingEnabled : bool

当启用模糊或阴影效果且此属性设置为 true（默认）时，项目大小会根据blurMax 和blurMultiplier 自动填充。请注意，paddingRect 始终会添加到尺寸中。

性能说明：为获得最佳性能，项目大小应尽可能小。

性能说明：会导致项目大小调整；请勿在动画过程中更改此属性。

另请参阅 paddingRect 。


blur : real

该属性定义了对源应用模糊（半径）的程度。

数值范围从 0.0（无模糊）到 1.0（完全模糊）。默认情况下，该属性设置为0.0 （无变化）。完全模糊的程度受blurMax 和blurMultiplier 的影响。

性能说明：如果不需要在模糊动画的任何一点接近 1.0，可考虑减少blurMax 或blurMultiplier 以获得最佳性能。


blurEnabled : bool

启用模糊效果。

性能说明：会导致着色器更改；请勿在动画过程中更改此属性。


blurMax : int

该属性定义了模糊值为 1.0 时的最大像素半径。

该值的有效范围为 2（微模糊）至 64（高模糊）。默认情况下，该属性设置为32 。为获得最佳性能，请根据需要选择尽可能小的值。

注意： 模糊和阴影效果都会受到影响。

性能说明：会导致着色器更改；请勿在动画过程中更改此属性。

性能说明：会导致项目大小的调整；请勿在动画过程中更改此属性。


blurMultiplier : real

该属性定义了扩展模糊半径的乘数。

数值范围从 0.0（不乘以）到 inf。默认情况下，该属性设置为0.0 。增加乘数可扩展模糊半径，但会降低模糊质量。对于更大的模糊半径，该选项比blurMax 更有效，因为它不会增加纹理查找次数。

注意： 这对模糊和阴影效果都有影响。

性能说明：会导致项目的大小调整；请勿在动画期间更改此属性。


brightness : real

该属性定义了源亮度的增减幅度。

数值范围为-1.0 至 1.0。默认情况下，该属性设置为0.0 （不变）。


colorization : real

该属性通过colorizationColor 定义光源着色的程度。

数值范围从 0.0（未着色）到 1.0（完全着色）。默认情况下，该属性设置为0.0 （无变化）。


colorizationColor : color

该属性定义了用于对源进行着色的 RGBA 颜色值。

默认情况下，该属性设置为Qt.rgba(1.0, 0.0, 0.0, 1.0) （红色）。

另请参阅 colorization 。


contrast : real

该属性定义信号源对比度的增减程度。

数值范围为-1.0 至 1.0。默认情况下，该属性设置为0.0 （不变）。


fragmentShader : string [read-only]

以只读方式访问当前使用的片段着色器的文件名。


hasProxySource : bool [read-only]

当MultiEffect 在内部为source 项目创建ShaderEffectSource 时，返回值为 true；当source 项目按原样使用时，返回值为 false。例如，当源为Image 元素或Item 并将layer.enabled 设置为true 时，就不需要这个额外的代理源。


itemRect : rect [read-only]

只读访问效果项矩形。例如，可用于查看项目覆盖的区域。

另请参阅 paddingRect 和autoPaddingEnabled 。


maskEnabled : bool

启用遮罩效果。

性能说明：会导致着色器更改；请勿在动画期间更改此属性。


maskInverted : bool

该属性会将遮罩切换到相反的一侧；在maskThresholdMin 和maskThresholdMax 之间的内容将被遮罩掉，而不是遮罩掉 和 以外的内容。

默认情况下，该属性设置为false 。


maskSource : Item

屏蔽效果的源项目。应指向ShaderEffectSource 、设置为layer.enabled 的项目true 或可直接用作纹理源的项目（例如Image ）。源项的 alpha 通道用于遮罩。

如果遮罩源和源的尺寸不同，则会拉伸遮罩源图像以匹配源的尺寸。


maskSpreadAtMax : real

该属性定义了maskThresholdMax 附近遮罩边缘的平滑度。使用较高的扩散值，可通过在透明遮罩像素与不透明遮罩像素之间添加内插值来软化过渡。

该值范围从 0.0（锐利的遮罩边缘）到 1.0（平滑的遮罩边缘）。默认情况下，该属性设置为0.0 。


maskSpreadAtMin : real

该属性定义了maskThresholdMin 附近遮罩边缘的平滑度。设置较高的扩散值，可通过在透明遮罩像素与不透明遮罩像素之间添加内插值，软化从透明遮罩像素向不透明遮罩像素的过渡。

该值范围从 0.0（锐利的遮罩边缘）到 1.0（平滑的遮罩边缘）。默认情况下，该属性设置为0.0 。


maskThresholdMax : real

该属性定义了遮罩像素的上阈值。Alpha 值低于该属性的屏蔽像素将用于完全屏蔽源项中的相应像素。具有较高 alpha 值的屏蔽像素用于将源项目字母化显示。

数值范围从 0.0（alpha 值 0）到 1.0（alpha 值 255）。默认情况下，该属性设置为1.0 。


maskThresholdMin : real

该属性定义了屏蔽像素的较低阈值。Alpha 值低于该属性的屏蔽像素将用于完全屏蔽源项中的相应像素。而具有较高 alpha 值的屏蔽像素则用于将源项目字母化显示。

数值范围从 0.0（alpha 值 0）到 1.0（alpha 值 255）。默认情况下，该属性设置为0.0 。


paddingRect : rect

设置该值可手动增大项目尺寸，以便适合模糊和/或阴影效果。如果autoPaddingEnabled 为 true，且未设置 paddingRect，则会根据blurMax 和blurMultiplier 对项目进行填充，以适应最大的模糊项目。启用阴影时，通常需要考虑shadowHorizontalOffset 和shadowVerticalOffset ，并相应调整 paddingRect。

下面是一个调整 paddingRect 的示例，其中autoPaddingEnabled 设置为 false，以便阴影适合MultiEffect 项目。

性能说明：为获得最佳性能，项目大小应尽可能小。

性能说明：会导致项目大小调整；请勿在动画过程中更改此属性。

另请参阅 autoPaddingEnabled 。


saturation : real

该属性定义了源饱和度的增减程度。

数值范围从 -1.0 （完全不饱和）到 inf。默认情况下，该属性设置为0.0 （无变化）。


shadowBlur : real

该属性定义阴影的模糊程度（半径）。

数值范围从 0.0（无模糊）到 1.0（完全模糊）。默认情况下，该属性设置为1.0 。完全模糊的程度受blurMax 和blurMultiplier 的影响。

性能说明：减少阴影模糊的最佳方法是将blurMax 设得更小（如果项目模糊不需要它）。切记不要在动画期间调整blurMax 。


shadowColor : color

该属性定义了用于阴影的 RGBA 颜色值。例如，当阴影用于模拟发光效果时，它就非常有用。

默认情况下，该属性设置为Qt.rgba(0.0, 0.0, 0.0, 1.0) （黑色）。


shadowEnabled : bool

启用阴影效果。

性能说明：会导致着色器更改；请勿在动画过程中更改此属性。


shadowHorizontalOffset : real

该属性定义阴影从项目中心的水平偏移。

数值范围为 -inf 至 inf。默认情况下，该属性设置为0.0 。

注意： 在将阴影位置偏离中心并添加shadowBlur 时，如果希望阴影不被剪切，可能还需要相应增加paddingRect 。


shadowOpacity : real

该属性定义了阴影的不透明度。该值与shadowColor alpha 值相乘。

数值范围从 0.0（完全透明）到 1.0（完全不透明）。默认情况下，该属性设置为1.0 。


shadowScale : real

该属性定义阴影的比例。缩放从项目中心开始。

数值范围为 0 至 inf。默认情况下，该属性设置为1.0 。

注意： 增加 shadowScale 时，可能还需要相应增加paddingRect ，以避免阴影被剪切。


shadowVerticalOffset： real

此属性定义阴影从项目中心的垂直偏移。

数值范围从 -inf 到 inf。默认情况下，该属性设置为0.0 。

注意： 在将阴影位置偏离中心并添加shadowBlur 时，如果希望阴影不被剪切，可能还需要相应增加paddingRect 。


source : Item

此属性包含用作效果源的项目。如果需要，MultiEffect 将在内部生成一个ShaderEffectSource 作为纹理源。

注： 不支持让效果包含自身，例如将源设置为效果的父项。

注： 如果源项layer.enabled 设置为 true，则将直接使用。当源被隐藏时，这对性能很有好处，通常也是人们所希望的。但如果源项仍然可见，而效果添加了填充（autoPaddingEnabled,paddingRect ），则填充会影响源项的外观。

另请参阅 hasProxySource 。


vertexShader : string [read-only]

以只读方式访问当前使用的顶点着色器的文件名。


信号文档

shaderChanged()

当所使用的着色器发生变化时会发出该信号。

注： 相应的处理程序是onShaderChanged 。

另请参见 fragmentShader 和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.