QML ShaderEffectItem Element

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:

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

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

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