diff options
authorLaszlo Agocs <>2021-05-03 11:58:17 +0200
committerQt Cherry-pick Bot <>2021-05-03 20:58:40 +0000
commit5a3ac0157c4b11d09bcbce3c59c3134ac119dd8c (patch)
parent0291b37529436b92bd4b7159d2d9447764617d05 (diff)
ShaderEffect docs: Clarify vertex output/input naming requirements
To be complemented by an rhi change that adds verification for this and prints a warning with mismatching names. The common use case with ShaderEffect is to provide a fragment shader only, while using the default, built-in vertex shader. In this case one must be aware of how to correctly declare the texture coordinates input, and this was not very clear in the docs. In short, we need to advise that the fragment shader input must be declared as qt_TexCoord0 at location 0 in order to be portable. Just having a matching location number but a different name is not sufficient. (because with old GLSL versions the location qualifier will not be there at all and matching is name based) Task-number: QTBUG-92500 Task-number: QTBUG-93370 Change-Id: I975557e9a754db8e7c69b86531a2d873f059c7ce Reviewed-by: Christian Strømme <> (cherry picked from commit 40959164bbc0e7144b3ba3e426296d0de61d60f5) Reviewed-by: Qt Cherry-pick Bot <>
1 files changed, 21 insertions, 2 deletions
diff --git a/src/quick/items/qquickshadereffect.cpp b/src/quick/items/qquickshadereffect.cpp
index 05f82d558f..caabd541b6 100644
--- a/src/quick/items/qquickshadereffect.cpp
+++ b/src/quick/items/qquickshadereffect.cpp
@@ -110,7 +110,10 @@ QT_BEGIN_NAMESPACE
\note It is only the vertex input location that matters in practice. The
names are freely changeable, while the location must always be \c 0 for
- vertex position, \c 1 for texture coordinates.
+ vertex position, \c 1 for texture coordinates. However, be aware that this
+ applies to vertex inputs only, and is not necessarily true for output
+ variables from the vertex shader that are then used as inputs in the
+ fragment shader (typically, the interpolated texture coordinates).
The following uniforms are predefined:
@@ -267,6 +270,18 @@ QT_BEGIN_NAMESPACE
or the opacity, because at run time there is one single uniform buffer that
is exposed to both the vertex and fragment shader.
+ \warning Unlike with vertex inputs, passing data between the vertex and
+ fragment shader may, depending on the underlying graphics API, require the
+ same names to be used, a matching location is not always sufficient. Most
+ prominently, when specifying a fragment shader while relying on the default,
+ built-in vertex shader, the texture coordinates are passed on as \c
+ qt_TexCoord0 at location \c 0, and therefore it is strongly advised that the
+ fragment shader declares the input with the same name
+ (qt_TexCoord0). Failing to do so may lead to issues on some platforms, for
+ example when running with a non-core profile OpenGL context where the
+ underlying GLSL shader source code has no location qualifiers and matching
+ is based on the variable names during to shader linking process.
\section1 ShaderEffect and Item Layers
The ShaderEffect type can be combined with \l {Item Layers} {layered items}.
@@ -436,7 +451,11 @@ QT_BEGIN_NAMESPACE
\li The vertex shader outputs and fragment shader inputs are up to the
shader code to define. The fragment shader must have a \c vec4 output at
- location 0 (typically called \c fragColor).
+ location 0 (typically called \c fragColor). For maximum portability, vertex
+ outputs and fragment inputs should use both the same location number and the
+ same name. When specifying only a fragment shader, the texture coordinates
+ are passed in from the built-in vertex shader as \c{vec2 qt_TexCoord0} at
+ location \c 0, as shown in the example snippets above.
\li Uniform variables outside a uniform block are not legal. Rather,
uniform data must be declared in a uniform block with binding point \c 0.