Back to Qt.io
Contact Us Blog Download Qt

ShaderEffectSource QML Type

将一个 Qt Quick项目渲染成纹理并显示出来。更多

Import Statement: import QtQuick
Inherits:

Item

属性

方法

详细说明

该 ShaderEffectSource 类型可将sourceItem 渲染成纹理并显示在场景中。在绘制纹理时，sourceItem 就像绘制一个完全不透明的根项目一样。因此，sourceItem 本身可以是不可见的，但仍会出现在纹理中。

您可以将 ShaderEffectSource 用作

  • ShaderEffect 中的纹理源。这样，您就可以将自定义着色器效果应用到任何 Qt Quick项目。
  • 复杂项目的缓存。复杂的项目可以渲染一次到纹理中，然后就可以自由地进行动画，而无需在每一帧中再次渲染复杂的项目。
  • 不透明度层。通过 ShaderEffectSource，您可以将不透明度应用到作为一个组的项目上，而不是单独应用到每个项目上。

import QtQuick 2.0

Rectangle {
    width: 200
    height: 100
    gradient: Gradient {
        GradientStop { position: 0; color: "white" }
        GradientStop { position: 1; color: "black" }
    }
    Row {
        opacity: 0.5
        Item {
            id: foo
            width: 100; height: 100
            Rectangle { x: 5; y: 5; width: 60; height: 60; color: "red" }
            Rectangle { x: 20; y: 20; width: 60; height: 60; color: "orange" }
            Rectangle { x: 35; y: 35; width: 60; height: 60; color: "yellow" }
        }
        ShaderEffectSource {
            width: 100; height: 100
            sourceItem: foo
        }
    }
}

ShaderEffectSource 类型不会将任何鼠标或键盘输入重定向到sourceItem 。如果将visible 设为 false 或将opacity 设为 0 以隐藏sourceItem ，它将不再对输入做出反应。如果 ShaderEffectSource 要取代sourceItem ，通常需要隐藏sourceItem ，同时仍要处理输入。为此，可以使用hideSource 属性。

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

注意： ShaderEffectSource 依靠 FBO 多重采样支持来反锯齿边缘。如果底层硬件不支持该功能（大多数嵌入式图形芯片都不支持），ShaderEffectSource 中渲染的边缘将不会反锯齿。补救的方法之一是将效果源的大小增加一倍，并使用smooth: true （这是平滑的默认值）进行渲染。这相当于 4 倍多重采样，但代价是性能降低和内存占用增加。

警告 在大多数情况下，使用 ShaderEffectSource 会降低性能，而在所有情况下，它都会增加视频内存的使用量。由于某些 OpenGL 实现支持多采样后缓冲区，但不支持多采样帧缓冲区对象，因此通过 ShaderEffectSource 进行渲染也可能导致质量下降。

属性文档

format : enumeration

该属性定义了背景纹理的格式。当该项目用作ShaderEffect 的源纹理时，修改该属性最为合理。

常量说明
ShaderEffectSource.RGBA8
ShaderEffectSource.RGBA16F
ShaderEffectSource.RGBA32F
ShaderEffectSource.Alpha从 Qt 6.0 开始，此值不使用，实际效果与RGBA8 相同。
ShaderEffectSource.RGB从 Qt 6.0 开始，此值不使用，实际效果与RGBA8 相同。
ShaderEffectSource.RGBA从 Qt 6.0 开始，此值不在使用中，实际效果与RGBA8 相同。

hideSource : bool

如果该属性为 true，sourceItem 将被隐藏，但仍会渲染到纹理中。与通过将visible 设置为 false 来隐藏sourceItem 不同，将此属性设置为 true 不会阻止鼠标或键盘输入到达sourceItem 。当ShaderEffectSource 被锚定在sourceItem 的顶部并意在取代 时，该属性非常有用。


live : bool

如果该属性为 true，则每当sourceItem 更新时，纹理就会更新。否则，即使sourceItem 被分配了一个新项目，它也将是一个冻结的图像。该属性默认为 true。


mipmap : bool

如果此属性为 true，则会为纹理生成 mipmaps。

注意： 某些 OpenGL ES 2 实现不支持非二倍幂纹理的 mipmapping。


recursive : bool

如果ShaderEffectSource 对自身有依赖性，请将此属性设为 true。着色器效果源（ShaderEffectSources）会形成一个依赖链，其中一个ShaderEffectSource 可以是另一个sourceItem 的一部分。如果该链中存在循环，ShaderEffectSource 最终可能会尝试渲染到它作为源使用的相同纹理中，而这是 OpenGL 所不允许的。当该属性设置为 true 时，将分配一个额外的纹理，以便ShaderEffectSource 可以保留上一帧的纹理副本。这样，它就可以渲染成一个纹理，并使用前一帧的纹理作为源。

将此属性和live 都设置为 true 将导致场景图连续渲染。由于ShaderEffectSource 依赖于自身，更新它意味着它会立即再次变脏。


samples : int

该属性允许请求多采样渲染。

默认情况下，只要整个窗口启用了多采样，就会启用多采样，前提是使用的场景图渲染器和底层图形 API 支持多采样。

通过将该值设置为 2、4 等，可以为场景的一部分请求多采样渲染，而无需为整个场景启用多采样。这样，多采样只应用于给定的子树，由于多采样不会应用于场景的其他部分，因此可以显著提高性能。

注： 无论图层的大小如何，启用多重采样都会带来潜在的高昂成本，因为它会产生与硬件和驱动程序相关的性能和内存成本。

注： 该属性只有在支持多采样渲染缓冲区和帧缓冲区混合时才有效。否则，该值将被忽略。


sourceItem : Item

该属性用于保存要渲染到纹理中的项目。在live 为 true 时将其设置为空，将释放纹理资源。


sourceRect : rect

该属性定义了要渲染到纹理中的sourceItem 矩形区域。源矩形可以大于sourceItem 本身。如果矩形为空（默认值），则整个sourceItem 都将渲染到纹理中。


textureMirroring : enumeration

该属性定义了生成的 OpenGL 纹理的镜像方式。默认值为ShaderEffectSource.MirrorVertically 。如果生成的纹理被自定义着色器（如ShaderEffect 指定的着色器）直接访问，自定义镜像可能会很有用。镜像对ShaderEffectSource 项目本身的用户界面表现没有影响。

常量说明
ShaderEffectSource.NoMirroring无镜像
ShaderEffectSource.MirrorHorizontally生成的纹理沿 X 轴翻转。
ShaderEffectSource.MirrorVertically生成的纹理沿 Y 轴翻转。

textureSize : size

此属性用于保存纹理的像素大小。如果为空（默认值），则使用源矩形的大小。

注： 此值以像素为单位，因为它直接控制纹理对象的大小。

注意： 某些平台对帧缓存对象的大小有限制，这意味着实际纹理大小可能大于请求的大小。


wrapMode : enumeration

该属性定义了与纹理相关的 OpenGL 封装模式。当该项目用作ShaderEffect 的源纹理时，修改该属性最为合理。

默认值为ShaderEffectSource.ClampToEdge 。

常量说明
ShaderEffectSource.ClampToEdgeGL_CLAMP_TO_EDGE 水平和垂直模式
ShaderEffectSource.RepeatHorizontally水平方向为 GL_REPEAT，垂直方向为 GL_CLAMP_TO_EDGE
ShaderEffectSource.RepeatVerticallyGL_CLAMP_TO_EDGE 水平方向，GL_REPEAT 垂直方向
ShaderEffectSource.Repeat水平和垂直均为 GL_REPEAT

注意： 某些 OpenGL ES 2 实现不支持使用非二倍幂纹理的 GL_REPEAT 包模式。


方法文档

scheduleUpdate()

安排在下一帧重新渲染纹理。当live 为 false 时，使用此方法更新纹理。


© 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.