<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- shadereffectitem.cpp -->
<title>Qt 4.8: QML ShaderEffectItem Element</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="qdeclarativeelements.html">QML Elements</a></li>
<li>QML ShaderEffectItem Element</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<p class="naviNextPrevious headerNavi">
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<h1 class="title">QML ShaderEffectItem Element</h1>
<span class="subtitle"></span>
<!-- $$$ShaderEffectItem-brief -->
<p>The ShaderEffectItem object alters the output of given item with OpenGL shaders. <a href="#details">More...</a></p>
<!-- @@@ShaderEffectItem -->
<p>Inherits <a href="qml-item.html">Item</a></p>
<ul>
<li><a href="qml-shadereffectitem-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2>Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-shadereffectitem.html#blending-prop">blending</a></b></b> : bool</li>
<li class="fn"><b><b><a href="qml-shadereffectitem.html#fragmentShader-prop">fragmentShader</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-shadereffectitem.html#meshResolution-prop">meshResolution</a></b></b> : QSize</li>
<li class="fn"><b><b><a href="qml-shadereffectitem.html#vertexShader-prop">vertexShader</a></b></b> : string</li>
</ul>
<!-- $$$ShaderEffectItem-description -->
<a name="details"></a>
<h2>Detailed Description</h2>
<p>ShaderEffectItem is available in the <b>Qt.labs.shaders 1.0</b> module. <i>Elements in the Qt.labs module are not guaranteed to remain compatible in future versions.</i></p>
<p>This element provides preliminary support for embedding OpenGL shader code into QML, and may be heavily changed or removed in later versions.</p>
<p>Requirement for the use of shaders is that the application is either using Qt OpenGL graphicssystem or is using OpenGL by setting <a href="qglwidget.html">QGLWidget</a> as the viewport to <a href="qdeclarativeview.html">QDeclarativeView</a> (depending on which one is the recommened way in the targeted platform).</p>
<p>ShaderEffectItem internal behaviour is such that during the paint event it first renders its <a href="qml-shadereffectsource.html">ShaderEffectSource</a> items into a OpenGL framebuffer object which can be used as a texture. If the <a href="qml-shadereffectsource.html">ShaderEffectSource</a> 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.</p>
<p>It is possible to define one or more ShaderEffectItems to be a <a href="qml-shadereffectsource.html">ShaderEffectSource</a> 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.</p>
<p>A standard set of vertex attributes are provided for the shaders:</p>
<ul>
<li>qt_Vertex - The primary position of the vertex.</li>
<li>qt_MultiTexCoord0 - The texture co-ordinate at each vertex for texture unit 0.</li>
</ul>
<p>Additionally following uniforms are available for shaders:</p>
<ul>
<li>qt_Opacity - Effective opacity of the item.</li>
<li>qt_ModelViewProjectionMatrix - current 4x4 transformation matrix of the item.</li>
</ul>
<p>Furthermore, it is possible to utilize automatic QML propertybinding into vertex- and fragment shader uniforms. Conversions are done according to the table below:</p>
<table class="generic">
<thead><tr class="qt-style"><th >QML property</th><th >GLSL uniform</th></tr></thead>
<tr valign="top" class="odd"><td >property double foo: 1.0</td><td >uniform highp float foo</td></tr>
<tr valign="top" class="even"><td >property real foo: 1.0</td><td >uniform highp float foo</td></tr>
<tr valign="top" class="odd"><td >property bool foo: true</td><td >uniform bool foo</td></tr>
<tr valign="top" class="even"><td >property int foo: 1</td><td >uniform int foo</td></tr>
<tr valign="top" class="odd"><td >property variant foo: Qt.point(1,1)</td><td >uniform highp vec2 foo</td></tr>
<tr valign="top" class="even"><td >property variant foo: Qt.size(1, 1)</td><td >uniform highp vec2 foo</td></tr>
<tr valign="top" class="odd"><td >property variant foo: Qt.rect(1, 1, 2, 2)</td><td >uniform highp vec4 foo</td></tr>
<tr valign="top" class="even"><td >property color foo: "#00000000"</td><td >uniform lowp vec4 foo</td></tr>
<tr valign="top" class="odd"><td >property variant foo: Qt.vector3d(1.0, 2.0, 0.0)</td><td >uniform highp vec3 foo</td></tr>
<tr valign="top" class="even"><td >property variant foo: <a href="qml-shadereffectsource.html">ShaderEffectSource</a> { SourceItem: bar }</td><td >uniform lowp sampler2D foo</td></tr>
</table>
<p><b>Note:</b> 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.</p>
<p>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. <a href="qml-shadereffectsource.html">ShaderEffectSource</a> referring to textLabel is bound to sampler2D uniform inside the fragment shader code.</p>
<pre class="qml"> import QtQuick 1.0
import Qt.labs.shaders 1.0
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">300</span>
<span class="name">height</span>: <span class="number">300</span>
<span class="name">color</span>: <span class="string">"black"</span>
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">textLabel</span>
<span class="name">text</span>: <span class="string">"Hello World"</span>
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">font</span>.pixelSize: <span class="number">32</span>
<span class="name">color</span>: <span class="string">"white"</span>
}
<span class="type">ShaderEffectItem</span> {
property <span class="type"><a href="qml-variant.html">variant</a></span> <span class="name">source</span>: <span class="name">ShaderEffectSource</span> { <span class="name">sourceItem</span>: <span class="name">textLabel</span>; <span class="name">hideSource</span>: <span class="number">true</span> }
property <span class="type"><a href="qml-real.html">real</a></span> <span class="name">wiggleAmount</span>: <span class="number">0.005</span>
<span class="name">anchors</span>.fill: <span class="name">textLabel</span>
<span class="name">fragmentShader</span>: <span class="string">"
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);
}
"</span>
}
}</pre>
<p class="centerAlign"><img src="images/shaderexample.png" alt="" /></p><!-- @@@ShaderEffectItem -->
<h2>Property Documentation</h2>
<!-- $$$blending -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="blending-prop"></a><span class="name">blending</span> : <span class="type"><a href="qml-bool.html">bool</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property defines whether item is drawn using blending.</p>
<p>If true, the RGBA pixel output from the fragment shader is blended with the pixel RGBA-values already in the framebuffer.</p>
<p>If false, fragment shader output is written to framebuffer as such.</p>
<p>Usually drawing without blending is slightly faster, thus disabling blending might be a good choice when item is used as a background element.</p>
<p><b>Note:</b> 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.</p>
<p>The default value is true.</p>
</div></div><!-- @@@blending -->
<br/>
<!-- $$$fragmentShader -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="fragmentShader-prop"></a><span class="name">fragmentShader</span> : <span class="type"><a href="qml-string.html">string</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property holds the OpenGL fragment shader code.</p>
<p>The default fragment shader is following:</p>
<pre class="cpp"> varying highp vec2 qt_TexCoord0;
uniform sampler2D source;
<span class="type">void</span> main(<span class="type">void</span>)
{
gl_FragColor <span class="operator">=</span> texture2D(source<span class="operator">,</span> qt_TexCoord0<span class="operator">.</span>st);
}</pre>
</div></div><!-- @@@fragmentShader -->
<br/>
<!-- $$$meshResolution -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="meshResolution-prop"></a><span class="name">meshResolution</span> : <span class="type"><a href="qsize.html">QSize</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property defines to how many triangles the item is divided into before its vertices are passed to the vertex shader.</p>
<p>Triangles are defined as triangle strips and the amount of triangles can be controlled separately for x and y-axis.</p>
<p>The default value is <a href="qsize.html">QSize</a>(1,1).</p>
</div></div><!-- @@@meshResolution -->
<br/>
<!-- $$$vertexShader -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="vertexShader-prop"></a><span class="name">vertexShader</span> : <span class="type"><a href="qml-string.html">string</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property holds the OpenGL vertex shader code.</p>
<p>The default vertex shader is following:</p>
<pre class="cpp"> uniform highp mat4 qt_ModelViewProjectionMatrix;
attribute highp vec4 qt_Vertex;
attribute highp vec2 qt_MultiTexCoord0;
varying highp vec2 qt_TexCoord0;
<span class="type">void</span> main(<span class="type">void</span>)
{
qt_TexCoord0 <span class="operator">=</span> qt_MultiTexCoord0;
gl_Position <span class="operator">=</span> qt_ModelViewProjectionMatrix <span class="operator">*</span> qt_Vertex;
}</pre>
</div></div><!-- @@@vertexShader -->
<br/>
<p class="naviNextPrevious footerNavi">
</p>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
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. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
