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 <christian.stromme@qt.io>
(cherry picked from commit 40959164bbc0e7144b3ba3e426296d0de61d60f5)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

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.