MultiEffect QML 类型

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

导入语句	import QtQuick.Effects
继承	Item

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

属性

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 中废弃的 Qt 图形效果的后继者，它将对源项应用后处理效果。与 Qt 图形效果模块相比，MultiEffect 将多个效果（模糊、阴影、着色等）合并为单独的项和着色器，使其更适合多个效果。有多种着色器变体，最优化的一种会根据使用的功能进行选择。

MultiEffect 专门针对最常用的效果设计，并且可以轻松进行动画处理。如果 MultiEffect 不包含您需要的效果，请考虑使用 Qt Quick 效果制作器实现自定义效果。有关着色器效果的信息，请参阅 ShaderEffect 参考文档。

示例用法

以下简单示例显示了如何对项应用饱和度效果

import QtQuick
import QtQuick.Effects

...
Image {
    id: sourceItem
    source: "qt_logo_green_rgb.png"
    visible: false
}
MultiEffect {
    source: sourceItem
    anchors.fill: sourceItem
    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，否则效果会超出窗口/屏幕的“外部”。

属性文档

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（不乘法）到无穷大。默认情况下，此属性设置为0.0。增加乘数扩展了模糊半径，但降低了模糊质量。这对于比blurMax更大的模糊半径来说是一个更有效的选项，因为它不会增加纹理查找的数量。

注意：这会影响模糊和阴影效果。

性能说明： 将导致项大小调整；不要在动画期间更改此属性。

brightness : real

此属性定义了源亮度增加或减少的量。

值范围从-1.0到1.0。默认情况下，此属性设置为0.0（无变化）。

colorization : real

此属性定义了源用colorizationColor着色多少。

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

colorizationColor : color

此属性定义用于着色源的字节码color值。

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

参见colorization.

contrast : real

此属性定义了源对比度增加或减少的量。

值范围从-1.0到1.0。默认情况下，此属性设置为0.0（无变化）。

fragmentShader : string [只读]

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

hasProxySource : bool [只读]

当MultiEffect在内部为source项创建ShaderEffectSource时返回true，当直接使用source项时返回false。例如，当source是Image元素或其layer.enabled属性设置为客户时，不需要额外的代理源。

itemRect : rect [只读]

读取只读访问到效果项矩形。这可以用来查看项覆盖的区域。

另请参阅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值的遮罩像素用来将源项进行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.

饱和度 : 实数

此属性定义了原始饱和度的增加或减少量。

值的范围从 -1.0（完全去饱和）到无穷大。默认情况下，该属性设置为 0.0（没有变化）。

阴影模糊 : 实数

此属性定义了应用于阴影的模糊程度（半径）。

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

性能提示：减少阴影模糊的最佳方法是将 blurMax 设置得较小（如果不需要items的模糊效果）。只是要记住，不要在动画期间调整 blurMax。

阴影颜色 : 颜色

此属性定义了用于阴影的 RGBA 颜色值。当需要模拟发光效果时非常有用。

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

阴影启用 : 布尔值

启用阴影效果。

性能提示：导致着色器更改；不要在动画期间更改此属性。

阴影水平偏移 : 实数

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

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

注意：当将阴影位置移离中心并添加 shadowBlur 时，你可能还需要相应地增加 paddingRect，以便阴影不会被裁剪。

阴影不透明度 : 实数

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

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

阴影缩放 : 实数

此属性定义了阴影的比例。缩放从项目中心应用。

值 ranges from 0 to inf. 默认情况下，该属性设置为 1.0。

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

阴影垂直偏移 : 实数

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

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

注意：当将阴影位置移离中心并添加 shadowBlur 时，你可能还需要相应地增加 paddingRect，以便阴影不会被裁剪。

源 : 项目

此属性持有用作效果源的项目。如果需要，多效果将内部生成一个 ShaderEffectSource 作为纹理源。

注意：不支持效果包含自身，例如通过将源设置为效果的父元素。

注意：如果源项目已将 layer.enabled 设置为 true，则它将被直接使用。当源被隐藏时，这有利于性能并且通常是期望的，但如果源保持可见并且效果添加了填充（autoPaddingEnabled，paddingRect），则该填充可能会影响源项目的外观。

另请参阅：hasProxySource。

顶点着色器 : 字符串 [只读]

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

信号文档

shaderChanged()

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

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

另请参阅：fragmentShader 和 vertexShader。