MultiEffect QML Type

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

• 所有成员的列表，包括继承的成员

属性

• 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

信号

• shaderChanged()

详细说明

MultiEffect 类型是 Qt 5 中QtGraphical Effects的继任者，它为source 项应用后处理效果。 与Qt XML的 ` Graphical Effects` 模块不同，`MultiEffect` 允许将多种效果（如模糊、阴影、着色等）组合到单个项和着色器中。若您仅需单一效果且不希望产生额外开销，可使用 `MultiEffect `；但您也可以利用它对单个项应用多种效果，而无需付出多次渲染的代价。

MultiEffect 专为最常见的特效而设计，且易于实现动画效果。如果 MultiEffect 中不包含您需要的特效，请考虑使用 Qt Quick Effect Maker。有关着色器效果的更多信息，请参阅ShaderEffect 参考文档。

请注意，MultiEffect 类型会在源项旁边渲染一个新的视觉项。 若要将效果应用于源对象，需将新的 MultiEffect 对象放置在源对象的位置上。如果源对象和 MultiEffect 对象均不为不透明，则两个对象都可能可见，从而可能无法获得预期效果。若要隐藏源对象，请执行以下任一操作：

• 将源项的visible: false 属性设为True。此时，源项将完全不会被渲染，也无法接收触摸或点击输入。
• 将源对象的opacity: 0 属性设置为1。此时，源对象完全透明，但仍可接收触摸或点击输入。

使用示例

以下示例演示了如何对项目应用饱和度效果：

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 ）始终处于启用状态，因此使用它们不会增加额外的开销。
• 请参阅可能改变着色器或效果项大小的属性的“性能注意事项”，并在动画过程中不要修改这些属性。
• 当不使用 MultiEffect 时，请记得将其visible 属性设置为 false，以避免在后台渲染这些效果。
• 模糊和阴影是消耗资源最多的效果。使用这些效果时，应优先增加blurMultiplier 而非blurMax ，并避免使用会进行动画的source 项，这样就不必在每一帧中都重新生成模糊效果。
• 请将特效应用于尺寸最优的 QML 元素，因为像素越多，GPU 的工作量就越大。当将模糊特效应用于整个背景时，请务必将autoPaddingEnabled 设置为 false，否则特效会“超出”窗口或屏幕范围。

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

• 在多个效果中使用同一源项并保持其不变。
• 通过使用ShaderEffectSource.sourceRect 来使用源项的一部分。
• 通过使用ShaderEffectSource.textureSize 属性，降低源项的分辨率，例如为了获得更好的性能。

属性文档

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通道将用于蒙版处理。

如果 maskSource 和源对象的尺寸不同，则会将 maskSource 图像拉伸以匹配源对象的尺寸。

maskSpreadAtMax : real

此属性定义了maskThresholdMax 附近蒙版边缘的平滑程度。使用较大的“扩散”值可在透明蒙版像素与不透明蒙版像素之间插入插值值，从而使两者的过渡更加平滑。

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

maskSpreadAtMin : real

此属性定义了maskThresholdMin 附近蒙版边缘的平滑程度。设置较高的“扩散”值可通过在透明蒙版像素与不透明蒙版像素之间添加插值值，从而柔化两者之间的过渡。

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

maskThresholdMax : real

此属性定义了蒙版像素的上限阈值。Alpha 值低于该阈值的蒙版像素将完全遮盖源项中的对应像素；Alpha 值高于该阈值的蒙版像素则用于将源项与显示内容进行 Alpha 混合。

该值的取值范围为 0.0（Alpha 值为 0）到 1.0（Alpha 值为 255）。默认情况下，该属性设置为1.0 。

maskThresholdMin : real

此属性定义了蒙版像素的下限阈值。Alpha 值低于此属性的蒙版像素将用于完全遮盖源项目中的相应像素。Alpha 值高于此属性的蒙版像素将用于将源项目与显示内容进行 Alpha 混合。

该值的取值范围为 0.0（Alpha 值为 0）到 1.0（Alpha 值为 255）。默认情况下，该属性设置为0.0 。

paddingRect : rect

将此选项设置为手动调整项目大小，以确保模糊效果和/或阴影能够适配。如果autoPaddingEnabled 为true且未设置paddingRect，系统将根据blurMax 和blurMultiplier ，为项目添加填充以适配最大程度的模糊效果。启用阴影时，通常需要考虑shadowHorizontalOffset 和shadowVerticalOffset ，并据此调整paddingRect。

以下是一个示例，展示了如何将autoPaddingEnabled 设置为false来调整paddingRect，以便阴影能够完全位于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 。

shadowOpacity : real

此属性用于定义阴影的不透明度。该值将与shadowColor 的透明度值相乘。

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

shadowScale : real

此属性定义了阴影的缩放比例。缩放操作以项的中心为基准进行。

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

shadowVerticalOffset : real

此属性定义了阴影相对于项目中心的垂直偏移量。

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

source : Item

该属性用于存储将作为效果源的对象。如有需要，MultiEffect 会在内部生成一个ShaderEffectSource 作为纹理源。

另请参阅 hasProxySource 。

vertexShader : string [read-only]

对当前使用的顶点着色器的文件名具有只读访问权限。

信号文档

shaderChanged()

当使用的着色器发生变化时，会触发此信号。

另请参阅 fragmentShader 和vertexShader 。