Home · All Classes · Modules

QGLShaderProgram Class Reference
^{^{[QtOpenGL module]}}

The QGLShaderProgram class allows OpenGL shader programs to be linked and used. More...

Inherits QObject.

Methods

__init__ (self, QObject parent = None)
__init__ (self, QGLContext context, QObject parent = None)
bool addShader (self, QGLShader shader)
bool addShaderFromSourceCode (self, QGLShader.ShaderType type, QByteArray source)
bool addShaderFromSourceCode (self, QGLShader.ShaderType type, QString source)
bool addShaderFromSourceFile (self, QGLShader.ShaderType type, QString fileName)
int attributeLocation (self, QByteArray name)
int attributeLocation (self, QString name)
bool bind (self)
bindAttributeLocation (self, QByteArray name, int location)
bindAttributeLocation (self, QString name, int location)
disableAttributeArray (self, int location)
disableAttributeArray (self, str name)
enableAttributeArray (self, int location)
enableAttributeArray (self, str name)
int geometryInputType (self)
int geometryOutputType (self)
int geometryOutputVertexCount (self)
bool isLinked (self)
bool link (self)
QString log (self)
int programId (self)
release (self)
removeAllShaders (self)
removeShader (self, QGLShader shader)
setAttributeArray (self, int location, sequence values)
setAttributeArray (self, str name, sequence values)
setAttributeBuffer (self, int location, int type, int offset, int tupleSize, int stride = 0)
setAttributeBuffer (self, str name, int type, int offset, int tupleSize, int stride = 0)
setAttributeValue (self, int location, float value)
setAttributeValue (self, int location, float x, float y)
setAttributeValue (self, int location, float x, float y, float z)
setAttributeValue (self, int location, float x, float y, float z, float w)
setAttributeValue (self, int location, QVector2D value)
setAttributeValue (self, int location, QVector3D value)
setAttributeValue (self, int location, QVector4D value)
setAttributeValue (self, int location, QColor value)
setAttributeValue (self, str name, float value)
setAttributeValue (self, str name, float x, float y)
setAttributeValue (self, str name, float x, float y, float z)
setAttributeValue (self, str name, float x, float y, float z, float w)
setAttributeValue (self, str name, QVector2D value)
setAttributeValue (self, str name, QVector3D value)
setAttributeValue (self, str name, QVector4D value)
setAttributeValue (self, str name, QColor value)
setGeometryInputType (self, int inputType)
setGeometryOutputType (self, int outputType)
setGeometryOutputVertexCount (self, int count)
setUniformValue (self, int location, int value)
setUniformValue (self, int location, float value)
setUniformValue (self, int location, float x, float y)
setUniformValue (self, int location, float x, float y, float z)
setUniformValue (self, int location, float x, float y, float z, float w)
setUniformValue (self, int location, QVector2D value)
setUniformValue (self, int location, QVector3D value)
setUniformValue (self, int location, QVector4D value)
setUniformValue (self, int location, QColor color)
setUniformValue (self, int location, QPoint point)
setUniformValue (self, int location, QPointF point)
setUniformValue (self, int location, QSize size)
setUniformValue (self, int location, QSizeF size)
setUniformValue (self, int location, QMatrix2x2 value)
setUniformValue (self, int location, QMatrix2x3 value)
setUniformValue (self, int location, QMatrix2x4 value)
setUniformValue (self, int location, QMatrix3x2 value)
setUniformValue (self, int location, QMatrix3x3 value)
setUniformValue (self, int location, QMatrix3x4 value)
setUniformValue (self, int location, QMatrix4x2 value)
setUniformValue (self, int location, QMatrix4x3 value)
setUniformValue (self, int location, QMatrix4x4 value)
setUniformValue (self, int location, QTransform value)
setUniformValue (self, str name, int value)
setUniformValue (self, str name, float value)
setUniformValue (self, str name, float x, float y)
setUniformValue (self, str name, float x, float y, float z)
setUniformValue (self, str name, float x, float y, float z, float w)
setUniformValue (self, str name, QVector2D value)
setUniformValue (self, str name, QVector3D value)
setUniformValue (self, str name, QVector4D value)
setUniformValue (self, str name, QColor color)
setUniformValue (self, str name, QPoint point)
setUniformValue (self, str name, QPointF point)
setUniformValue (self, str name, QSize size)
setUniformValue (self, str name, QSizeF size)
setUniformValue (self, str name, QMatrix2x2 value)
setUniformValue (self, str name, QMatrix2x3 value)
setUniformValue (self, str name, QMatrix2x4 value)
setUniformValue (self, str name, QMatrix3x2 value)
setUniformValue (self, str name, QMatrix3x3 value)
setUniformValue (self, str name, QMatrix3x4 value)
setUniformValue (self, str name, QMatrix4x2 value)
setUniformValue (self, str name, QMatrix4x3 value)
setUniformValue (self, str name, QMatrix4x4 value)
setUniformValue (self, str name, QTransform value)
setUniformValueArray (self, int location, sequence values)
setUniformValueArray (self, str name, sequence values)
list-of-QGLShader shaders (self)
int uniformLocation (self, QByteArray name)
int uniformLocation (self, QString name)

Static Methods

bool hasOpenGLShaderPrograms (QGLContext context = None)

Detailed Description

The QGLShaderProgram class allows OpenGL shader programs to be linked and used.

Introduction

This class supports shader programs written in the OpenGL Shading Language (GLSL) and in the OpenGL/ES Shading Language (GLSL/ES).

QGLShader and QGLShaderProgram shelter the programmer from the details of compiling and linking vertex and fragment shaders.

The following example creates a vertex shader program using the supplied source code. Once compiled and linked, the shader program is activated in the current QGLContext by calling QGLShaderProgram.bind():

 QGLShader shader(QGLShader.Vertex);
 shader.compileSourceCode(code);

 QGLShaderProgram program(context);
 program.addShader(shader);
 program.link();

 program.bind();

Writing portable shaders

Shader programs can be difficult to reuse across OpenGL implementations because of varying levels of support for standard vertex attributes and uniform variables. In particular, GLSL/ES lacks all of the standard variables that are present on desktop OpenGL systems: gl_Vertex, gl_Normal, gl_Color, and so on. Desktop OpenGL lacks the variable qualifiers highp, mediump, and lowp.

The QGLShaderProgram class makes the process of writing portable shaders easier by prefixing all shader programs with the following lines on desktop OpenGL:

 #define highp
 #define mediump
 #define lowp

This makes it possible to run most GLSL/ES shader programs on desktop systems. The programmer should restrict themselves to just features that are present in GLSL/ES, and avoid standard variable names that only work on the desktop.

Simple shader example

 program.addShaderFromSourceCode(QGLShader.Vertex,
     "attribute highp vec4 vertex;\n"
     "uniform highp mat4 matrix;\n"
     "void main(void)\n"
     "{\n"
     "   gl_Position = matrix * vertex;\n"
     "}");
 program.addShaderFromSourceCode(QGLShader.Fragment,
     "uniform mediump vec4 color;\n"
     "void main(void)\n"
     "{\n"
     "   gl_FragColor = color;\n"
     "}");
 program.link();
 program.bind();

 int vertexLocation = program.attributeLocation("vertex");
 int matrixLocation = program.uniformLocation("matrix");
 int colorLocation = program.uniformLocation("color");

With the above shader program active, we can draw a green triangle as follows:

 static GLfloat const triangleVertices[] = {
     60.0f,  10.0f,  0.0f,
     110.0f, 110.0f, 0.0f,
     10.0f,  110.0f, 0.0f
 };

 QColor color(0, 255, 0, 255);

 QMatrix4x4 pmvMatrix;
 pmvMatrix.ortho(rect());

 program.enableAttributeArray(vertexLocation);
 program.setAttributeArray(vertexLocation, triangleVertices, 3);
 program.setUniformValue(matrixLocation, pmvMatrix);
 program.setUniformValue(colorLocation, color);

 glDrawArrays(GL_TRIANGLES, 0, 3);

 program.disableAttributeArray(vertexLocation);

Binary shaders and programs

Binary shaders may be specified using glShaderBinary() on the return value from QGLShader.shaderId(). The QGLShader instance containing the binary can then be added to the shader program with addShader() and linked in the usual fashion with link().

Binary programs may be specified using glProgramBinaryOES() on the return value from programId(). Then the application should call link(), which will notice that the program has already been specified and linked, allowing other operations to be performed on the shader program.

Method Documentation

QGLShaderProgram.init (self, QObject parent = None)

The parent argument, if not None, causes self to be owned by Qt instead of PyQt.

Constructs a new shader program and attaches it to parent. The program will be invalid until addShader() is called.

The shader program will be associated with the current QGLContext.

See also addShader().

QGLShaderProgram.init (self, QGLContext context, QObject parent = None)

The parent argument, if not None, causes self to be owned by Qt instead of PyQt.

Constructs a new shader program and attaches it to parent. The program will be invalid until addShader() is called.

The shader program will be associated with context.

See also addShader().

bool QGLShaderProgram.addShader (self, QGLShader shader)

Adds a compiled shader to this shader program. Returns true if the shader could be added, or false otherwise.

Ownership of the shader object remains with the caller. It will not be deleted when this QGLShaderProgram instance is deleted. This allows the caller to add the same shader to multiple shader programs.

See also addShaderFromSourceCode(), addShaderFromSourceFile(), removeShader(), link(), and removeAllShaders().

bool QGLShaderProgram.addShaderFromSourceCode (self, QGLShader.ShaderType type, QByteArray source)

Compiles source as a shader of the specified type and adds it to this shader program. Returns true if compilation was successful, false otherwise. The compilation errors and warnings will be made available via log().

This function is intended to be a short-cut for quickly adding vertex and fragment shaders to a shader program without creating an instance of QGLShader first.

See also addShader(), addShaderFromSourceFile(), removeShader(), link(), log(), and removeAllShaders().

bool QGLShaderProgram.addShaderFromSourceCode (self, QGLShader.ShaderType type, QString source)

This is an overloaded function.

This function is intended to be a short-cut for quickly adding vertex and fragment shaders to a shader program without creating an instance of QGLShader first.

See also addShader(), addShaderFromSourceFile(), removeShader(), link(), log(), and removeAllShaders().

bool QGLShaderProgram.addShaderFromSourceFile (self, QGLShader.ShaderType type, QString fileName)

Compiles the contents of fileName as a shader of the specified type and adds it to this shader program. Returns true if compilation was successful, false otherwise. The compilation errors and warnings will be made available via log().

This function is intended to be a short-cut for quickly adding vertex and fragment shaders to a shader program without creating an instance of QGLShader first.

See also addShader() and addShaderFromSourceCode().

int QGLShaderProgram.attributeLocation (self, QByteArray name)

Returns the location of the attribute name within this shader program's parameter list. Returns -1 if name is not a valid attribute for this shader program.

See also uniformLocation() and bindAttributeLocation().

int QGLShaderProgram.attributeLocation (self, QString name)

This is an overloaded function.

Returns the location of the attribute name within this shader program's parameter list. Returns -1 if name is not a valid attribute for this shader program.

bool QGLShaderProgram.bind (self)

Binds this shader program to the active QGLContext and makes it the current shader program. Any previously bound shader program is released. This is equivalent to calling glUseProgram() on programId(). Returns true if the program was successfully bound; false otherwise. If the shader program has not yet been linked, or it needs to be re-linked, this function will call link().

See also link() and release().

QGLShaderProgram.bindAttributeLocation (self, QByteArray name, int location)

Binds the attribute name to the specified location. This function can be called before or after the program has been linked. Any attributes that have not been explicitly bound when the program is linked will be assigned locations automatically.

When this function is called after the program has been linked, the program will need to be relinked for the change to take effect.

See also attributeLocation().

QGLShaderProgram.bindAttributeLocation (self, QString name, int location)

This is an overloaded function.

When this function is called after the program has been linked, the program will need to be relinked for the change to take effect.

See also attributeLocation().

This parameter takes effect the next time the program is linked.

This function was introduced in Qt 4.7.

See also setGeometryInputType().

int QGLShaderProgram.geometryOutputType (self)

Returns the geometry shader output type, if active.

This parameter takes effect the next time the program is linked.

This function was introduced in Qt 4.7.

See also setGeometryOutputType().

int QGLShaderProgram.geometryOutputVertexCount (self)

Returns the maximum number of vertices the current geometry shader program will produce, if active.

This parameter takes effect the ntext time the program is linked.

This function was introduced in Qt 4.7.

bool QGLShaderProgram.hasOpenGLShaderPrograms (QGLContext context = None)

Returns true if shader programs written in the OpenGL Shading Language (GLSL) are supported on this system; false otherwise.

The context is used to resolve the GLSL extensions. If context is null, then QGLContext.currentContext() is used.

bool QGLShaderProgram.isLinked (self)

Returns true if this shader program has been linked; false otherwise.

See also link().

bool QGLShaderProgram.link (self)

Links together the shaders that were added to this program with addShader(). Returns true if the link was successful or false otherwise. If the link failed, the error messages can be retrieved with log().

Subclasses can override this function to initialize attributes and uniform variables for use in specific shader programs.

If the shader program was already linked, calling this function again will force it to be re-linked.

See also addShader() and log().

QString QGLShaderProgram.log (self)

Returns the errors and warnings that occurred during the last link() or addShader() with explicitly specified source code.

See also link().

int QGLShaderProgram.programId (self)

Returns the OpenGL identifier associated with this shader program.

See also QGLShader.shaderId().

QGLShaderProgram.release (self)

Releases the active shader program from the current QGLContext. This is equivalent to calling glUseProgram(0).

See also bind().

QGLShaderProgram.removeAllShaders (self)

Removes all of the shaders that were added to this program previously. The QGLShader objects for the shaders will not be deleted if they were constructed externally. QGLShader objects that are constructed internally by QGLShaderProgram will be deleted.

See also addShader() and removeShader().

QGLShaderProgram.removeShader (self, QGLShader shader)

Removes shader from this shader program. The object is not deleted.

See also addShader(), link(), and removeAllShaders().

QGLShaderProgram.setAttributeArray (self, int location, sequence values)

Sets an array of vertex values on the attribute at location in this shader program. The tupleSize indicates the number of components per vertex (1, 2, 3, or 4), and the stride indicates the number of bytes between vertices. A default stride value of zero indicates that the vertices are densely packed in values.

The array will become active when enableAttributeArray() is called on the location. Otherwise the value specified with setAttributeValue() for location will be used.

See also setAttributeValue(), setUniformValue(), enableAttributeArray(), and disableAttributeArray().

QGLShaderProgram.setAttributeArray (self, str name, sequence values)

Sets an array of 2D vertex values on the attribute at location in this shader program. The stride indicates the number of bytes between vertices. A default stride value of zero indicates that the vertices are densely packed in values.

The array will become active when enableAttributeArray() is called on the location. Otherwise the value specified with setAttributeValue() for location will be used.

See also setAttributeValue(), setUniformValue(), enableAttributeArray(), and disableAttributeArray().

QGLShaderProgram.setAttributeBuffer (self, int location, int type, int offset, int tupleSize, int stride = 0)

Sets an array of vertex values on the attribute at location in this shader program, starting at a specific offset in the currently bound vertex buffer. The stride indicates the number of bytes between vertices. A default stride value of zero indicates that the vertices are densely packed in the value array.

The type indicates the type of elements in the vertex value array, usually GL_FLOAT, GL_UNSIGNED_BYTE, etc. The tupleSize indicates the number of components per vertex: 1, 2, 3, or 4.

The array will become active when enableAttributeArray() is called on the location. Otherwise the value specified with setAttributeValue() for location will be used.

This function was introduced in Qt 4.7.

See also setAttributeArray().

QGLShaderProgram.setAttributeBuffer (self, str name, int type, int offset, int tupleSize, int stride = 0)

This is an overloaded function.

Sets an array of vertex values on the attribute called name in this shader program, starting at a specific offset in the currently bound vertex buffer. The stride indicates the number of bytes between vertices. A default stride value of zero indicates that the vertices are densely packed in the value array.

The type indicates the type of elements in the vertex value array, usually GL_FLOAT, GL_UNSIGNED_BYTE, etc. The tupleSize indicates the number of components per vertex: 1, 2, 3, or 4.

The array will become active when enableAttributeArray() is called on the name. Otherwise the value specified with setAttributeValue() for name will be used.

This function was introduced in Qt 4.7.

See also setAttributeArray().