From a0ee51bef5425947ede6b35b3c7606dfff36c3c6 Mon Sep 17 00:00:00 2001 From: Gunnar Sletta Date: Tue, 24 Apr 2012 16:08:55 +0200 Subject: [PATCH] Docs for QSGimpleMaterialShader Change-Id: I769eb68a1703a2cc7379af702fb888d3e9697300 Reviewed-by: Geir Vattekar --- src/quick/scenegraph/coreapi/qsgmaterial.cpp | 11 +- src/quick/scenegraph/scenegraph.pri | 4 +- src/quick/scenegraph/util/qsgsimplematerial.cpp | 202 ++++++++++++++++++++++++ 3 files changed, 215 insertions(+), 2 deletions(-) create mode 100644 src/quick/scenegraph/util/qsgsimplematerial.cpp diff --git a/src/quick/scenegraph/coreapi/qsgmaterial.cpp b/src/quick/scenegraph/coreapi/qsgmaterial.cpp index 9f0def4..850db69 100644 --- a/src/quick/scenegraph/coreapi/qsgmaterial.cpp +++ b/src/quick/scenegraph/coreapi/qsgmaterial.cpp @@ -47,7 +47,12 @@ QT_BEGIN_NAMESPACE /*! \class QSGMaterialShader - \brief The QSGMaterialShader class implements a material renders geometry. + \brief The QSGMaterialShader class represents an OpenGL shader program + in the renderer. + + The QSGMaterialShader API is very low-level. A more convenient API, which + provides almost all the same features, is available through + QSGSimpleMaterialShader. The QSGMaterial and QSGMaterialShader form a tight relationship. For one scene graph (including nested graphs), there is one unique QSGMaterialShader @@ -437,6 +442,10 @@ static void qt_print_material_count() \class QSGMaterial \brief The QSGMaterial class encapsulates rendering state for a shader program. + The QSGMaterial API is very low-level. A more convenient API, which + provides almost all the same features, is available through + QSGSimpleMaterialShader. + The QSGMaterial and QSGMaterialShader subclasses form a tight relationship. For one scene graph (including nested graphs), there is one unique QSGMaterialShader instance which encapsulates the QOpenGLShaderProgram the scene graph uses diff --git a/src/quick/scenegraph/scenegraph.pri b/src/quick/scenegraph/scenegraph.pri index 4391ccb..a58e9b4 100644 --- a/src/quick/scenegraph/scenegraph.pri +++ b/src/quick/scenegraph/scenegraph.pri @@ -18,7 +18,8 @@ SOURCES += \ $$PWD/coreapi/qsgnode.cpp \ $$PWD/coreapi/qsgnodeupdater.cpp \ $$PWD/coreapi/qsgrenderer.cpp \ - $$PWD/coreapi/qsgrendernode.cpp + $$PWD/coreapi/qsgrendernode.cpp \ + scenegraph/util/qsgsimplematerial.cpp # Util API HEADERS += \ @@ -85,3 +86,4 @@ SOURCES += \ + diff --git a/src/quick/scenegraph/util/qsgsimplematerial.cpp b/src/quick/scenegraph/util/qsgsimplematerial.cpp new file mode 100644 index 0000000..38758b4 --- /dev/null +++ b/src/quick/scenegraph/util/qsgsimplematerial.cpp @@ -0,0 +1,202 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the QtQml module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms and +** conditions contained in a signed written agreement between you and Nokia. +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QSGSimpleMaterialShader + + \brief The QSGSimpleMaterialShader provides a convenient way of + building custom materials for the scene graph. + + \inmodule QtQuick + + Where the QSGMaterial and QSGMaterialShader API requires a bit of + boilerplate code to create a functioning material, the + QSGSimpleMaterialShader tries to hide some of this through the use + of templates. + + QSGSimpleMaterialShader::vertexShader() and + QSGSimpleMaterialShader::fragmentShader() are used to specify the + actual shader source code. The names of the vertex attributes + should be listed in the QSGSimpleMaterialShader::attributes() + + QSGSimpleMaterialShader::updateState() is used to push the material + state to the OpenGL shader program. + + The actual OpenGL shader program is accessible through the + QSGSimpleMaterialShader::program() function. + + Each QSGSimpleMaterialShader implementation operates on a unique + state struct. The state struct must be declared using the + \c {QSG_DECLARE_SIMPLE_SHADER} macro. + + Here is a simple example of a custom solid-color: + + \code + struct Color + { + float r, g, b, a; + }; + + class MinimalShader : public QSGSimpleMaterialShader + { + QSG_DECLARE_SIMPLE_SHADER(MinimalShader, Color) + public: + + const char *vertexShader() const { + return + "attribute highp vec4 vertex; \n" + "uniform highp mat4 qt_Matrix; \n" + "void main() { \n" + " gl_Position = qt_Matrix * vertex; \n" + "}"; + } + + const char *fragmentShader() const { + return + "uniform lowp float qt_Opacity; \n" + "uniform lowp vec4 color; \n" + "void main() { \n" + " gl_FragColor = color * qt_Opacity; \n" + "}"; + } + + QList attributes() const { + return QList() << "vertex"; + } + + void updateState(const Color *color, const Color *) { + program()->setUniformValue("color", color->r, color->g, color->b, color->a); + } + + }; + \endcode + + Instances of materials using this shader can be created using the + createMaterial() function which will be defined by the + QSG_DECLARE_SIMPLE_SHADER macro. + + \code + QSGSimpleMaterial *material = MinimalShader::createMaterial(); + material->state()->r = 1; + material->state()->g = 0; + material->state()->b = 0; + material->state()->a = 1; + + node->setMaterial(material); + \endcode + + The scene graph will often try to find materials that have the + same or at least similar state so that these can be batched + together inside the renderer, which gives better performance. To + specify sortable material states, use + QSG_DECLARE_SIMPLE_COMPARABLE_SHADER instead of + QSG_DECLARE_SIMPLE_SHADER. The state struct must then also define + the function: + + \code + int compare(const Type *other) const; + \endcode + + \warning The QSGSimpleMaterialShader relies on template + instantiation to create a QSGMaterialType which the scene graph + renderer internally uses to identify this shader. For this reason, + the unique QSGSimpleMaterialShader implemenation must be + instantiated with a unique C++ type. + + */ + +/*! + \fn QList QSGSimpleMaterialShader::attributes() const + + Returns a list of names, declaring the vertex attributes in the + vertex shader. +*/ + +/*! + \fn void QSGSimpleMaterialShader::updateState(const State *newState, const State *oldState) + + Called whenever the state of this shader should be updated, + typical for each new set of geometries being drawn. + + Both the old and the new state are passed in so that the + implementation can compare and minimize the state changes when + applicable. +*/ + +/*! + \fn const char *QSGSimpleMaterialShader::vertexShader() const + + Called when the shader is being initialized to get the vertex + shader source code. + + The contents returned from this function should never change. +*/ + + +/*! + \fn const char *QSGSimpleMaterialShader::fragmentShader() const + + Called when the shader is being initialized to get the vertex + shader source code. + + The contents returned from this function should never change. +*/ + +/*! + \class QSGSimpleMaterial + + \brief The QSGSimpleMaterial class is a template generated class + used to store the state used with a QSGSimpleMateralShader. + + The state of the material is accessible through the template + generated state() function. + + \inmodule QtQuick + + \sa QSGSimpleMaterialShader +*/ + + + + + + + -- 2.7.4