1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtQuick module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40/*!
41 \class QSGSimpleMaterialShader
42
43 \brief The QSGSimpleMaterialShader class provides a convenient way of
44 building custom OpenGL-based materials for the scene graph.
45
46 \inmodule QtQuick
47 \ingroup qtquick-scenegraph-materials
48
49 \deprecated
50
51 \warning This utility class is only functional when running with the legacy
52 OpenGL renderer of the Qt Quick scenegraph. Its usage is not recommended in
53 new application code.
54
55 Where the QSGMaterial and QSGMaterialShader API requires a bit of
56 boilerplate code to create a functioning material, the
57 QSGSimpleMaterialShader tries to hide some of this through the use
58 of templates.
59
60 QSGSimpleMaterialShader::vertexShader() and
61 QSGSimpleMaterialShader::fragmentShader() are used to specify the
62 actual shader source code. The names of the vertex attributes
63 should be listed in the QSGSimpleMaterialShader::attributes()
64
65 QSGSimpleMaterialShader::updateState() is used to push the material
66 state to the OpenGL shader program.
67
68 The actual OpenGL shader program is accessible through the
69 QSGSimpleMaterialShader::program() function.
70
71 Each QSGSimpleMaterialShader implementation operates on a unique
72 state struct. The state struct must be declared using the
73 \c {QSG_DECLARE_SIMPLE_SHADER} macro.
74
75 Here is a simple example of a custom solid-color:
76
77 \code
78 struct Color
79 {
80 float r, g, b, a;
81 };
82
83 class MinimalShader : public QSGSimpleMaterialShader<Color>
84 {
85 QSG_DECLARE_SIMPLE_SHADER(MinimalShader, Color)
86 public:
87
88 const char *vertexShader() const {
89 return
90 "attribute highp vec4 vertex; \n"
91 "uniform highp mat4 qt_Matrix; \n"
92 "void main() { \n"
93 " gl_Position = qt_Matrix * vertex; \n"
94 "}";
95 }
96
97 const char *fragmentShader() const {
98 return
99 "uniform lowp float qt_Opacity; \n"
100 "uniform lowp vec4 color; \n"
101 "void main() { \n"
102 " gl_FragColor = color * qt_Opacity; \n"
103 "}";
104 }
105
106 QList<QByteArray> attributes() const {
107 return QList<QByteArray>() << "vertex";
108 }
109
110 void updateState(const Color *color, const Color *) {
111 program()->setUniformValue("color", color->r, color->g, color->b, color->a);
112 }
113
114 };
115 \endcode
116
117 Instances of materials using this shader can be created using the
118 createMaterial() function which will be defined by the
119 QSG_DECLARE_SIMPLE_SHADER macro.
120
121 \code
122 QSGSimpleMaterial<Color> *material = MinimalShader::createMaterial();
123 material->state()->r = 1;
124 material->state()->g = 0;
125 material->state()->b = 0;
126 material->state()->a = 1;
127
128 node->setMaterial(material);
129 \endcode
130
131 The scene graph will often try to find materials that have the
132 same or at least similar state so that these can be batched
133 together inside the renderer, which gives better performance. To
134 specify sortable material states, use
135 QSG_DECLARE_SIMPLE_COMPARABLE_SHADER instead of
136 QSG_DECLARE_SIMPLE_SHADER. The state struct must then also define
137 the function:
138
139 \code
140 int compare(const Type *other) const;
141 \endcode
142
143 \warning The QSGSimpleMaterialShader relies on template
144 instantiation to create a QSGMaterialType which the scene graph
145 renderer internally uses to identify this shader. For this reason,
146 the unique QSGSimpleMaterialShader implementation must be
147 instantiated with a unique C++ type.
148
149 \note All classes with QSG prefix should be used solely on the scene graph's
150 rendering thread. See \l {Scene Graph and Rendering} for more information.
151
152 \sa {Scene Graph - Simple Material}
153 */
154
155/*!
156 \macro QSG_DECLARE_SIMPLE_SHADER(Shader, State)
157 \relates QSGSimpleMaterialShader
158
159 This macro is used to declare a QSGMaterialType and a \c
160 createMaterial() function for \a Shader with the given \a State.
161 */
162
163/*!
164 \macro QSG_DECLARE_SIMPLE_COMPARABLE_SHADER(Shader, State)
165 \relates QSGSimpleMaterialShader
166
167 This macro is used to declare a QSGMaterialType and a \c
168 createMaterial() function for \a Shader with the given \a State,
169 where the \a State class must define a compare function on the
170 form:
171
172 \code
173 int compare(const State *other) const;
174 \endcode
175*/
176
177
178/*!
179 \fn template <typename State> char const *const *QSGSimpleMaterialShader<State>::attributeNames() const
180 \internal
181 */
182
183/*!
184 \fn template <typename State> void QSGSimpleMaterialShader<State>::initialize()
185 \internal
186 */
187
188/*!
189 \fn template <typename State> void QSGSimpleMaterialShader<State>::resolveUniforms()
190
191 Reimplement this function to resolve the location of named uniforms
192 in the shader program.
193
194 This function is called when the material shader is initialized.
195 */
196
197/*!
198 \fn template <typename State> const char *QSGSimpleMaterialShader<State>::uniformMatrixName() const
199
200 Returns the name for the transform matrix uniform of this item.
201 The default value is \c qt_Matrix.
202 */
203
204/*!
205 \fn template <typename State> const char *QSGSimpleMaterialShader<State>::uniformOpacityName() const
206
207 Returns the name for the opacity uniform of this item.
208 The default value is \c qt_Opacity.
209 */
210
211/*!
212 \fn template <typename State> void QSGSimpleMaterialShader<State>::updateState(const RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
213 \internal
214 */
215
216
217/*!
218 \fn template <typename State> QList<QByteArray> QSGSimpleMaterialShader<State>::attributes() const
219
220 Returns a list of names, declaring the vertex attributes in the
221 vertex shader.
222*/
223
224/*!
225 \fn template <typename State> void QSGSimpleMaterialShader<State>::updateState(const State *newState, const State *oldState)
226
227 Called whenever the state of this shader should be updated from
228 \a oldState to \a newState, typical for each new set of
229 geometries being drawn.
230
231 Both the old and the new state are passed in so that the
232 implementation can compare and minimize the state changes when
233 applicable.
234*/
235
236/*!
237 \class QSGSimpleMaterial
238
239 \deprecated
240
241 \inmodule QtQuick
242 \ingroup qtquick-scenegraph-materials
243
244 \brief The QSGSimpleMaterial class is a template generated class
245 used to store the state used with a QSGSimpleMateralShader.
246
247 The state of the material is accessible through the template
248 generated state() function.
249
250 \inmodule QtQuick
251
252 \note All classes with QSG prefix should be used solely on the scene graph's
253 rendering thread. See \l {Scene Graph and Rendering} for more information.
254
255 \sa QSGSimpleMaterialShader
256*/
257
258
259

source code of qtdeclarative/src/quick/scenegraph/util/qsgsimplematerial.cpp