QSGMaterialShader Class

Detailed Description

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 instance which encapsulates the QOpenGLShaderProgram the scene graph uses to render that material, such as a shader to flat coloring of geometry. Each QSGGeometryNode can have a unique QSGMaterial containing the how the shader should be configured when drawing that node, such as the actual color used to render the geometry.

An instance of QSGMaterialShader is never created explicitly by the user, it will be created on demand by the scene graph through QSGMaterial::createShader(). The scene graph will make sure that there is only one instance of each shader implementation through a scene graph.

The source code returned from vertexShader() is used to control what the material does with the vertiex data that comes in from the geometry. The source code returned from the fragmentShader() is used to control what how the material should fill each individual pixel in the geometry. The vertex and fragment source code is queried once during initialization, changing what is returned from these functions later will not have any effect.

The activate() function is called by the scene graph when a shader is is starting to be used. The deactivate function is called by the scene graph when the shader is no longer going to be used. While active, the scene graph may make one or more calls to updateState() which will update the state of the shader for each individual geometry to render.

The attributeNames() returns the name of the attributes used in the vertexShader(). These are used in the default implementation of activate() and deactivate() to decide whice vertex registers are enabled.

The initialize() function is called during program creation to allow subclasses to prepare for use, such as resolve uniform names in the vertexShader() and fragmentShader().

A minimal example:

class Shader : public QSGMaterialShader
{
public:
    const char *vertexShader() const {
        return
        "attribute highp vec4 vertex;          \n"
        "uniform highp mat4 matrix;            \n"
        "void main() {                         \n"
        "    gl_Position = matrix * vertex;    \n"
        "}";
    }

    const char *fragmentShader() const {
        return
        "uniform lowp float opacity;                            \n"
        "void main() {                                          \n"
                "    gl_FragColor = vec4(1, 0, 0, 1) * opacity; \n"
        "}";
    }

    char const *const *attributeNames() const
    {
        static char const *const names[] = { "vertex", 0 };
        return names;
    }

    void initialize()
    {
        QSGMaterialShader::initialize();
        m_id_matrix = program()->uniformLocation("matrix");
        m_id_opacity = program()->uniformLocation("opacity");
    }

    void updateState(const RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
    {
        Q_ASSERT(program()->isLinked());
        if (state.isMatrixDirty())
            program()->setUniformValue(m_id_matrix, state.combinedMatrix());
        if (state.isOpacityDirty())
            program()->setUniformValue(m_id_opacity, state.opacity());
    }

private:
    int m_id_matrix;
    int m_id_opacity;
};

Note: All classes with QSG prefix should be used solely on the scene graph's rendering thread. See Scene Graph and Rendering for more information.