ShaderEffectSource QML Type

Renders a Qt Quick item into a texture and displays it. More...

Import Statement:	`import QtQuick`
Inherits:	Item

List of all members, including inherited members

Properties

format : enumeration
hideSource : bool
live : bool
mipmap : bool
recursive : bool
samples : int
sourceItem : Item
sourceRect : rect
textureMirroring : enumeration
textureSize : size
wrapMode : enumeration

Methods

scheduleUpdate()

Detailed Description

The ShaderEffectSource type renders sourceItem into a texture and displays it in the scene. sourceItem is drawn into the texture as though it was a fully opaque root item. Thus sourceItem itself can be invisible, but still appear in the texture.

You can use the ShaderEffectSource as:

a texture source in a ShaderEffect. This allows you to apply custom shader effects to any Qt Quick item.
a cache for a complex item. The complex item can be rendered once into the texture, which can then be animated freely without the need to render the complex item again every frame.
an opacity layer. ShaderEffectSource allows you to apply an opacity to items as a group rather than each item individually.

 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
         }
     }
 }

The ShaderEffectSource type does not redirect any mouse or keyboard input to sourceItem. If you hide the sourceItem by setting visible to false or opacity to zero, it will no longer react to input. In cases where the ShaderEffectSource is meant to replace the sourceItem, you typically want to hide the sourceItem while still handling input. For this, you can use the hideSource property.

You can combine the ShaderEffectSource and the MultiEffect:

To use the same source item in multiple effects and to keep it unchanged.
To use a part of the source item, by using ShaderEffectSource.sourceRect.
To decrease the resolution of the source item, for example, for better performance, by using the ShaderEffectSource.textureSize property.

Note: The ShaderEffectSource relies on FBO multisampling support to antialias edges. If the underlying hardware does not support this, which is the case for most embedded graphics chips, edges rendered inside a ShaderEffectSource will not be antialiased. One way to remedy this is to double the size of the effect source and render it with smooth: true (this is the default value of smooth). This will be equivalent to 4x multisampling, at the cost of lower performance and higher memory use.

Warning: In most cases, using a ShaderEffectSource will decrease performance, and in all cases, it will increase video memory usage. Rendering through a ShaderEffectSource might also lead to lower quality since some OpenGL implementations support multisampled backbuffer, but not multisampled framebuffer objects.

Property Documentation

format : enumeration

This property defines the format of the backing texture. Modifying this property makes most sense when the item is used as a source texture of a ShaderEffect.

Constant	Description
`ShaderEffectSource.RGBA8`
`ShaderEffectSource.RGBA16F`
`ShaderEffectSource.RGBA32F`
`ShaderEffectSource.Alpha`	Starting with Qt 6.0, this value is not in use and has the same effect as `RGBA8` in practice.
`ShaderEffectSource.RGB`	Starting with Qt 6.0, this value is not in use and has the same effect as `RGBA8` in practice.
`ShaderEffectSource.RGBA`	Starting with Qt 6.0, this value is not in use and has the same effect as `RGBA8` in practice.

hideSource : bool

If this property is true, the sourceItem is hidden, though it will still be rendered into the texture. As opposed to hiding the sourceItem by setting visible to false, setting this property to true will not prevent mouse or keyboard input from reaching sourceItem. The property is useful when the ShaderEffectSource is anchored on top of, and meant to replace the sourceItem.

live : bool

If this property is true, the texture is updated whenever the sourceItem updates. Otherwise, it will be a frozen image, even if sourceItem is assigned a new item. The property is true by default.

mipmap : bool

If this property is true, mipmaps are generated for the texture.

Note: Some OpenGL ES 2 implementations do not support mipmapping of non-power-of-two textures.

recursive : bool

Set this property to true if the ShaderEffectSource has a dependency on itself. ShaderEffectSources form a dependency chain, where one ShaderEffectSource can be part of the sourceItem of another. If there is a loop in this chain, a ShaderEffectSource could end up trying to render into the same texture it is using as source, which is not allowed by OpenGL. When this property is set to true, an extra texture is allocated so that ShaderEffectSource can keep a copy of the texture from the previous frame. It can then render into one texture and use the texture from the previous frame as source.

Setting both this property and live to true will cause the scene graph to render continuously. Since the ShaderEffectSource depends on itself, updating it means that it immediately becomes dirty again.

samples : int

This property allows requesting multisampled rendering.

By default multisampling is enabled whenever multisampling is enabled for the entire window, assuming the scenegraph renderer in use and the underlying graphics API supports this.

By setting the value to 2, 4, etc. multisampled rendering can be requested for a part of the scene without enabling multisampling for the entire scene. This way multisampling is applied only to a given subtree, which can lead to significant performance gains since multisampling is not applied to other parts of the scene.

Note: Enabling multisampling can be potentially expensive regardless of the layer's size, as it incurs a hardware and driver dependent performance and memory cost.

Note: This property is only functional when support for multisample renderbuffers and framebuffer blits is available. Otherwise the value is silently ignored.

sourceItem : Item

This property holds the item to be rendered into the texture. Setting this to null while live is true, will release the texture resources.

sourceRect : rect

This property defines which rectangular area of the sourceItem to render into the texture. The source rectangle can be larger than sourceItem itself. If the rectangle is null, which is the default, the whole sourceItem is rendered to texture.

textureMirroring : enumeration

This property defines how the generated OpenGL texture should be mirrored. The default value is ShaderEffectSource.MirrorVertically. Custom mirroring can be useful if the generated texture is directly accessed by custom shaders, such as those specified by ShaderEffect. Mirroring has no effect on the UI representation of the ShaderEffectSource item itself.

Constant	Description
`ShaderEffectSource.NoMirroring`	No mirroring
`ShaderEffectSource.MirrorHorizontally`	The generated texture is flipped along X-axis.
`ShaderEffectSource.MirrorVertically`	The generated texture is flipped along Y-axis.

textureSize : size

This property holds the requested pixel size of the texture. If it is empty, which is the default, the size of the source rectangle is used.

Note: This value is in pixels since it directly controls the size of a texture object.

Note: Some platforms have a limit on how small framebuffer objects can be, which means the actual texture size might be larger than the requested size.

wrapMode : enumeration

This property defines the OpenGL wrap modes associated with the texture. Modifying this property makes most sense when the item is used as a source texture of a ShaderEffect.

The default value is ShaderEffectSource.ClampToEdge.

Constant	Description
`ShaderEffectSource.ClampToEdge`	GL_CLAMP_TO_EDGE both horizontally and vertically
`ShaderEffectSource.RepeatHorizontally`	GL_REPEAT horizontally, GL_CLAMP_TO_EDGE vertically
`ShaderEffectSource.RepeatVertically`	GL_CLAMP_TO_EDGE horizontally, GL_REPEAT vertically
`ShaderEffectSource.Repeat`	GL_REPEAT both horizontally and vertically

Note: Some OpenGL ES 2 implementations do not support the GL_REPEAT wrap mode with non-power-of-two textures.

Method Documentation

scheduleUpdate()

Schedules a re-rendering of the texture for the next frame. Use this to update the texture when live is false.

Contents

ShaderEffectSource QML Type

Properties

Methods

Detailed Description

Property Documentation

Method Documentation