QML ShaderEffectItem Element

The ShaderEffectItem object alters the output of given item with OpenGL shaders. More...

Inherits Item

List of all members, including inherited members

Properties

blending : bool
fragmentShader : string
meshResolution : QSize
vertexShader : string

Detailed Description

ShaderEffectItem is available in the Qt.labs.shaders 1.0 module. Elements in the Qt.labs module are not guaranteed to remain compatible in future versions.

This element provides preliminary support for embedding OpenGL shader code into QML, and may be heavily changed or removed in later versions.

Requirement for the use of shaders is that the application is either using Qt OpenGL graphicssystem or is using OpenGL by setting QGLWidget as the viewport to QDeclarativeView (depending on which one is the recommened way in the targeted platform).

ShaderEffectItem internal behaviour is such that during the paint event it first renders its ShaderEffectSource items into a OpenGL framebuffer object which can be used as a texture. If the ShaderEffectSource is defined to be an image, it is directly uploaded as a texture. The texture(s) containing the source pixelcontent are then bound to graphics pipeline texture units. Finally a textured mesh is passed to the vertex- and fragmentshaders which then produce the final output for the ShaderEffectItem. It is possible to alter the mesh structure by defining the amount vertices it contains, but currently it is not possible to import complex 3D-models to be used as the mesh.

It is possible to define one or more ShaderEffectItems to be a ShaderEffectSource for other ShaderEffectItems, but ShaderEffectItem should never be declared as a child element of its source item(s) because it would cause circular loop in the painting.

A standard set of vertex attributes are provided for the shaders:

qt_Vertex - The primary position of the vertex.
qt_MultiTexCoord0 - The texture co-ordinate at each vertex for texture unit 0.

Additionally following uniforms are available for shaders:

qt_Opacity - Effective opacity of the item.
qt_ModelViewProjectionMatrix - current 4x4 transformation matrix of the item.

Furthermore, it is possible to utilize automatic QML propertybinding into vertex- and fragment shader uniforms. Conversions are done according to the table below:

QML property	GLSL uniform
property double foo: 1.0	uniform highp float foo
property real foo: 1.0	uniform highp float foo
property bool foo: true	uniform bool foo
property int foo: 1	uniform int foo
property variant foo: Qt.point(1,1)	uniform highp vec2 foo
property variant foo: Qt.size(1, 1)	uniform highp vec2 foo
property variant foo: Qt.rect(1, 1, 2, 2)	uniform highp vec4 foo
property color foo: "#00000000"	uniform lowp vec4 foo
property variant foo: Qt.vector3d(1.0, 2.0, 0.0)	uniform highp vec3 foo
property variant foo: ShaderEffectSource { SourceItem: bar }	uniform lowp sampler2D foo

Note: The uniform precision definitions in the above table are not strict, it is possible to choose the uniform precision based on what is the most suitable for the shader code for that particular uniform.

The below example uses fragment shader to create simple wiggly effect to a text label. Automatic property binding takes care of binding the properties to the uniforms if their names are identical. ShaderEffectSource referring to textLabel is bound to sampler2D uniform inside the fragment shader code.

 import QtQuick 1.0
 import Qt.labs.shaders 1.0

 Rectangle {
     width: 300
     height: 300
     color: "black"

     Text {
         id: textLabel
         text: "Hello World"
         anchors.centerIn: parent
         font.pixelSize: 32
         color: "white"

     }

     ShaderEffectItem {
         property variant source: ShaderEffectSource { sourceItem: textLabel; hideSource: true }
         property real wiggleAmount: 0.005
         anchors.fill: textLabel

         fragmentShader: "
         varying highp vec2 qt_TexCoord0;
         uniform sampler2D source;
         uniform highp float wiggleAmount;
         void main(void)
         {
             highp vec2 wiggledTexCoord = qt_TexCoord0;
             wiggledTexCoord.s += sin(4.0 * 3.141592653589 * wiggledTexCoord.t) * wiggleAmount;
             gl_FragColor = texture2D(source, wiggledTexCoord.st);
         }
         "
     }
 }

Property Documentation

blending : bool

This property defines whether item is drawn using blending.

If true, the RGBA pixel output from the fragment shader is blended with the pixel RGBA-values already in the framebuffer.

If false, fragment shader output is written to framebuffer as such.

Usually drawing without blending is slightly faster, thus disabling blending might be a good choice when item is used as a background element.

Note: By default the pixel data in textures is stored in 32-bit premultiplied alpha format. This should be taken into account when blending or reading the pixel values in the fragment shader code.

The default value is true.

fragmentShader : string

This property holds the OpenGL fragment shader code.

The default fragment shader is following:

 varying highp vec2 qt_TexCoord0;
 uniform sampler2D source;
 void main(void)
 {
     gl_FragColor = texture2D(source, qt_TexCoord0.st);
 }

meshResolution : QSize

This property defines to how many triangles the item is divided into before its vertices are passed to the vertex shader.

Triangles are defined as triangle strips and the amount of triangles can be controlled separately for x and y-axis.

The default value is QSize(1,1).

vertexShader : string

This property holds the OpenGL vertex shader code.

The default vertex shader is following:

 uniform highp mat4 qt_ModelViewProjectionMatrix;
 attribute highp vec4 qt_Vertex;
 attribute highp vec2 qt_MultiTexCoord0;
 varying highp vec2 qt_TexCoord0;
 void main(void)
 {
     qt_TexCoord0 = qt_MultiTexCoord0;
     gl_Position = qt_ModelViewProjectionMatrix * qt_Vertex;
 }

Contents

QML ShaderEffectItem Element

Properties

Detailed Description

Property Documentation