QGLPainter Class

Member Function Documentation

QGLPainter::QGLPainter()

Constructs a new GL painter. Call begin() to attach the painter to a GL context.

See also begin().

QGLPainter::QGLPainter(QOpenGLContext * context)

Constructs a new GL painter and attaches it to context. It is not necessary to call begin() after construction.

See also begin().

QGLPainter::QGLPainter(QWindow * window)

Constructs a new GL painter and attaches it to the GL context associated with window. It is not necessary to call begin() after construction.

See also begin() and isActive().

QGLPainter::QGLPainter(QPainter * painter)

Constructs a new GL painter and attaches it to the GL context associated with painter. It is assumed that painter is the currently active painter and that it is associated with the current GL context.

If painter is not using an OpenGL paint engine, then isActive() will return false; true otherwise.

This constructor is typically used when mixing regular Qt painting operations and GL painting operations on a widget that is being drawn using the OpenGL graphics system.

See also begin() and isActive().

QGLPainter::QGLPainter(QGLAbstractSurface * surface)

Constructs a new GL painter and attaches it to the GL context associated with surface.

See also begin() and isActive().

QGLPainter::~QGLPainter() [virtual]

Destroys this GL painter.

int QGLPainter::addLight(const QGLLightParameters * parameters)

Adds a light to this painter, with the specified parameters. The lightTransform() for the light is set to the current modelViewMatrix(). Returns an identifier for the light.

Light parameters are stored in world co-ordinates, not eye co-ordinates. The lightTransform() specifies the transformation to apply to convert the world co-ordinates into eye co-ordinates when the light is used.

Note: the parameters may be ignored by effect() if it has some other way to determine the lighting conditions.

The light settings in the GL server will not be changed until update() is called.

See also removeLight(), light(), and mainLight().

int QGLPainter::addLight(const QGLLightParameters * parameters, const QMatrix4x4 & transform)

Adds a light to this painter, with the specified parameters. The lightTransform() for the light is set to transform. Returns an identifier for the light.

Light parameters are stored in world co-ordinates, not eye co-ordinates. The transform specifies the transformation to apply to convert the world co-ordinates into eye co-ordinates when the light is used.

Note: the parameters may be ignored by effect() if it has some other way to determine the lighting conditions.

The light settings in the GL server will not be changed until update() is called.

See also removeLight(), light(), and mainLight().

qreal QGLPainter::aspectRatio() const

Returns the aspect ratio of the viewport for adjusting projection transformations.

QGLAttributeSet QGLPainter::attributes() const

Returns the set of vertex attributes that have been set on the painter state by setVertexAttribute() and setVertexBundle() since the last call to clearAttributes().

The most common use for this function is to determine if specific attributes have been supplied on the painter so as to adjust the current drawing effect accordingly. The following example will use a lit texture effect if texture co-ordinates were provided in the vertex bundle, or a simple lit material effect if texture co-ordinates were not provided:

 painter.clearAttributes();
 painter.setVertexBundle(bundle);
 if (painter.attributes().contains(QGL::TextureCoord0))
     painter.setStandardEffect(QGL::LitModulateTexture2D);
 else
     painter.setStandardEffect(QGL::LitMaterial);

It is important to clear the attributes before setting the vertex bundle, so that attributes from a previous bundle will not leak through. Multiple vertex bundles may be supplied if they contain different parts of the same logical piece of geometry.

See also clearAttributes() and setVertexBundle().

bool QGLPainter::begin()

Begins painting on the current GL context. Returns false if there is no GL context current.

See also end().

bool QGLPainter::begin(QOpenGLContext * context)

Begins painting on context. If painting was already in progress, then this function will call end() first. The context will be made current if it is not already current.

Returns true if painting can begin; false otherwise.

All QGLPainter instances on a context share the same context state: matrices, the effect(), vertex attributes, etc. For example, calling ortho() on one QGLPainter instance for a context will alter the projectionMatrix() as seen by the other QGLPainter instances.

See also end() and isActive().

bool QGLPainter::begin(QWindow * window)

Begins GL painting on widget. Returns false if widget is null.

See also end().

bool QGLPainter::begin(QPainter * painter)

Begins painting on the GL context associated with painter. Returns false if painter is not using an OpenGL paint engine. It is assumed that painter is the currently active painter and that it is associated with the current GL context.

This function is typically used when mixing regular Qt painting operations and GL painting operations on a widget that is being drawn using the OpenGL graphics system.

See also end().

bool QGLPainter::begin(QGLAbstractSurface * surface)

Begins painting to surface. Returns false if surface is null or could not be activated.

See also end() and QGLAbstractSurface::activate().

QOpenGLShaderProgram * QGLPainter::cachedProgram(const QString & name) const

Returns the cached shader program associated with name; or null if name is not currently associated with a shader program.

See also setCachedProgram().

void QGLPainter::clearAttributes()

Clears the set of vertex attributes that have been set on the painter state by setVertexAttribute() and setVertexBundle(). See the documentation for attributes() for more information.

See also attributes().

void QGLPainter::clearPickObjects()

Clears the objectPickId() to pickColor() mappings that were used previously. This will also set objectPickId() to -1 and pickColor() to (0, 0, 0, 1).

The function call will be ignored if isPicking() is false.

See also objectPickId() and pickColor().

QColor QGLPainter::color() const

Returns the last color that was set with setColor(). The default value is (1, 1, 1, 1).

See also setColor().

QMatrix4x4 QGLPainter::combinedMatrix() const

Returns the result of multiplying the projectionMatrix() and the modelViewMatrix(). This combined matrix value is useful for setting uniform matrix values on shader programs.

Calling this function is more efficient than calling projectionMatrix() and modelViewMatrix() separately and multiplying the return values.

See also projectionMatrix(), modelViewMatrix(), and normalMatrix().

QOpenGLContext * QGLPainter::context() const

Returns the GL context that is bound to this painter, or null if it is not currently bound.

QGLAbstractSurface * QGLPainter::currentSurface() const

Returns the current drawing surface.

See also pushSurface(), popSurface(), and setSurface().

void QGLPainter::disableEffect()

Disables the current effect and sets userEffect() to null. Unlike setUserEffect() this not activate the standardEffect() until the next time effect() is called.

This function can be used to disable all effect-based drawing operations prior to performing raw GL calls. The next time effect() is called on this QGLPainter, the standardEffect() will be reactivated. An effect can also be reactivated by calling setUserEffect() or setStandardEffect().

See also userEffect() and standardEffect().

void QGLPainter::draw(QGL::DrawingMode mode, int count, int index = 0)

Draws primitives using count vertices from the arrays specified by setVertexAttribute(). The type of primitive to draw is specified by mode.

This operation will consume count values from the enabled arrays, starting at index.

See also update().

void QGLPainter::draw(QGL::DrawingMode mode, const QGLIndexBuffer & indexes)

This is an overloaded function.

Draws primitives using vertices from the arrays specified by setVertexAttribute(). The type of primitive to draw is specified by mode.

This operation will consume all of the elements of indexes, which are used to index into the enabled arrays.

If indexes has not been uploaded to the GL server as an index buffer, then this function will draw using a client-side array.

See also update() and QGLIndexBuffer::upload().

void QGLPainter::draw(QGL::DrawingMode mode, const QGLIndexBuffer & indexes, int offset, int count) [virtual]

This is an overloaded function.

Draws primitives using vertices from the arrays specified by setVertexAttribute(). The type of primitive to draw is specified by mode.

This operation will consume count elements of indexes, starting at offset, which are used to index into the enabled arrays.

If indexes has not been uploaded to the GL server as an index buffer, then this function will draw using a client-side array.

See also update() and QGLIndexBuffer::upload().

void QGLPainter::draw(QGL::DrawingMode mode, const ushort * indices, int count)

This is an overloaded function.

Draws primitives using vertices from the arrays specified by setVertexAttribute(). The type of primitive to draw is specified by mode.

This operation will consume count elements of indices, which are used to index into the enabled arrays.

See also update().

QGLAbstractEffect * QGLPainter::effect() const

Returns the current effect that is in use, which is userEffect() if it is not null, or the effect object associated with standardEffect() otherwise.

If isPicking() is true, then this will return the effect object that is being used to generate pick colors.

See also userEffect(), standardEffect(), and isPicking().

bool QGLPainter::end()

Ends GL painting. Returns true if painting was ended successfully; false if this painter was not bound to a GL context.

The GL context that was bound to this painter will not have QOpenGLContext::doneCurrent() called on it. It is the responsibility of the caller to terminate context operations.

The effect() will be left active in the GL context and will be assumed to still be active the next time begin() is called. If this assumption doesn't apply, then call disableEffect() to disable the effect before calling end().

This function will pop all surfaces from the surface stack, and return currentSurface() to null (the default drawing surface).

See also begin(), isActive(), and disableEffect().

QGL::Eye QGLPainter::eye() const

Returns the camera eye that is currently being used for stereo rendering. The default is QGL::NoEye.

The eye is used to adjust the camera position by a small amount when setCamera() is called.

See also setEye() and setCamera().

const QGLMaterial * QGLPainter::faceMaterial(QGL::Face face) const

Returns the material that is used for drawing face on polygons. If face is QGL::FrontFaces or QGL::AllFaces, then the front material is returned. If face is QGL::BackFaces, then the back material is returned.

See also setFaceMaterial() and setFaceColor().

bool QGLPainter::isActive() const

Returns true if this painter is currently bound to a GL context; false otherwise.

See also begin() and end().

bool QGLPainter::isCullable(const QVector3D & point) const

Returns true if point is outside the current viewing volume. This is used to perform object culling checks.

bool QGLPainter::isCullable(const QBox3D & box) const

Returns true if box is completely outside the current viewing volume. This is used to perform object culling checks.

bool QGLPainter::isFixedFunction() const

Returns true if the underlying OpenGL implementation is OpenGL 1.x or OpenGL/ES 1.x and only supports fixed-function OpenGL operations. Returns false if the underlying OpenGL implementation is using GLSL or GLSL/ES shaders.

If this function returns false, then the built-in effects will use shaders and QGLPainter will not update the fixed-function matrices in the OpenGL context when update() is called. User-supplied effects will need to use shaders also or update the fixed-function matrices themselves or call updateFixedFunction().

See also update() and updateFixedFunction().

bool QGLPainter::isPicking() const

Returns true if this painter is in object picking mode; false if this painter is in normal rendering mode.

See also setPicking() and objectPickId().

const QGLLightParameters * QGLPainter::light(int lightId) const

Returns the parameters for the light with the identifier lightId; or null if lightId is not valid or has been removed.

See also addLight(), removeLight(), and lightTransform().

const QGLLightModel * QGLPainter::lightModel() const

Returns the current lighting model.

See also setLightModel().

QMatrix4x4 QGLPainter::lightTransform(int lightId) const

Returns the modelview transformation for the light with the identifier lightId; or the identity matrix if lightId is not valid or has been removed.

See also addLight(), removeLight(), and light().

const QGLLightParameters * QGLPainter::mainLight() const

Returns the parameters for the main light in the scene.

The light parameters are specified in world co-ordinates at the point when setMainLight() was called. The mainLightTransform() must be applied to obtain eye co-ordinates.

This function is a convenience that returns the light with identifier 0. If light 0 is not currently enabled, then a default light is added to the painter with an identity transform and then returned as the main light.

See also setMainLight(), mainLightTransform(), and addLight().

QMatrix4x4 QGLPainter::mainLightTransform() const

Returns the modelview transformation matrix for the main light that was set at the time setMainLight() was called.

The light transform may be used by later painting operations to convert the light from world co-ordinates into eye co-ordinates. The eye transformation is set when the light is specified.

This function is a convenience that returns the tranform for the light with identifier 0. If light 0 is not enabled, then the function returns the identity matrix.

See also mainLight(), setMainLight(), and addLight().

int QGLPainter::maximumLightId() const

Returns the maximum light identifier currently in use on this painter; or -1 if there are no lights.

It is possible that some light identifiers less than maximumLightId() may be invalid because the lights have been removed. Use the following code to locate all enabled lights:

 int maxLightId = painter.maximumLightId();
 for (int lightId = 0; index <= maxLightId; ++index) {
     const QGLLightParameters *params = painter.light(lightId);
     if (params) {
         ...
     }
 }

See also addLight() and light().

QMatrix4x4Stack & QGLPainter::modelViewMatrix()

Returns a reference to the modelview matrix stack.

See also projectionMatrix(), combinedMatrix(), normalMatrix(), setCamera(), and worldMatrix().

QMatrix3x3 QGLPainter::normalMatrix() const

Returns the normal matrix corresponding to modelViewMatrix().

The normal matrix is the transpose of the inverse of the top-left 3x3 part of the 4x4 modelview matrix. If the 3x3 sub-matrix is not invertible, this function returns the identity.

See also modelViewMatrix() and combinedMatrix().

int QGLPainter::objectPickId() const

Returns the current object pick identifier. The default value is -1 which indicates that rendered objects should not have a pickColor() associated with them.

See also setObjectPickId(), clearPickObjects(), and pickObject().

QColor QGLPainter::pickColor() const

Returns the current pick color to use to render the object associated with objectPickId(). The returned color will be (0, 0, 0, 1) if objectPickId() is -1.

See also objectPickId() and clearPickObjects().

int QGLPainter::pickObject(int x, int y) const

Picks the color at (x, y) in the color buffer and returns the objectPickId() that corresponds to that color. Returns -1 if (x, y) is not positioned over a recognized object. The origin (0, 0) is assumed to be the bottom-left corner of the drawing surface.

See also objectPickId().

QGLAbstractSurface * QGLPainter::popSurface()

Pops the top-most drawing surface from the surface stack and returns it. The next object on the stack will be made the current drawing surface for context(). Returns null if the surface stack is already at the main surface (e.g. the window).

The UpdateViewport flag will be set to indicate that the glViewport() should be adjusted to the new surface extents when update() is next called.

See also pushSurface(), currentSurface(), and setSurface().

QMatrix4x4Stack & QGLPainter::projectionMatrix()

Returns a reference to the projection matrix stack.

It is recommended that setCamera() be used to set the projection matrix at the beginning of a scene rendering pass so that the eye position can be adjusted for stereo.

See also modelViewMatrix(), combinedMatrix(), and setCamera().

void QGLPainter::pushSurface(QGLAbstractSurface * surface)

Pushes surface onto the surface stack and makes it the current drawing surface for context(). If surface is null, then the current drawing surface will be set to the main surface (e.g. the window).

Note: the surface object must remain valid until popped from the stack or end() is called. All surfaces are popped from the stack by end().

The UpdateViewport flag will be set to indicate that the glViewport() should be adjusted to the extents of surface when update() is next called.

See also popSurface(), currentSurface(), setSurface(), and QGLAbstractSurface::activate().

void QGLPainter::removeLight(int lightId)

Removes the light with the specified lightId.

See also addLight() and light().

QGLRenderSequencer * QGLPainter::renderSequencer()

Returns the current render order sequencer.

See also QGLRenderSequencer.

void QGLPainter::setCachedProgram(const QString & name, QOpenGLShaderProgram * program)

Sets the cached shader program associated with name.

Effect objects can use this function to store pre-compiled and pre-linked shader programs in the painter for future use by the same effect. The program will be destroyed when context() is destroyed.

If program is null, then the program associated with name will be destroyed. If name is already present as a cached program, then it will be replaced with program.

Names that start with "qt." are reserved for use by Qt's internal effects.

See also cachedProgram().

void QGLPainter::setCamera(const QGLCamera * camera)

Sets the modelViewMatrix() and projectionMatrix() to the view defined by camera. If eye() is not QGL::NoEye, then the view will be adjusted for the camera's eye separation.

This function is typically called at the beginning of a scene rendering pass to initialize the modelview and projection matrices.

Note that this does not cause the painter to take ownership of the camera and it does not save the pointer value. The camera may be safely deleted after calling this function.

See also eye(), modelViewMatrix(), projectionMatrix(), and worldMatrix().

void QGLPainter::setClearColor(const QColor & color)

Sets the color to use to clear the color buffer when glClear() is called.

void QGLPainter::setColor(const QColor & color)

Sets the default fragment color for effects associated with this painter. This function does not apply the color to the effect until update() is called.

See also color() and update().

void QGLPainter::setEye(QGL::Eye eye)

Sets the camera eye that is currently being used for stereo rendering.

The eye is used to adjust the camera position by a small amount when setCamera() is called.

See also eye() and setCamera().

void QGLPainter::setFaceColor(QGL::Face face, const QColor & color)

Sets the material that is used for drawing face on polygons to color. This is a convenience function for setting materials to simple colors.

The RGB components of the ambient color of the material will be set to 20% of color, and the RGB components of the diffuse color of the material will be set to 80% of color. The alpha components of the ambient and diffuse material colors will both be set to the alpha component of color.

If face is QGL::FrontFaces, then the front material is set. If face is QGL::BackFaces, then the back material is set. If face is QGL::AllFaces, then both the front and back materials are set.

The material settings in the GL server will not be changed until update() is called.

See also faceMaterial() and setFaceMaterial().

void QGLPainter::setFaceMaterial(QGL::Face face, const QGLMaterial * value)

Sets the material that is used for drawing face on polygons to value. If face is QGL::FrontFaces, then the front material is set. If face is QGL::BackFaces, then the back material is set. If face is QGL::AllFaces, then both the front and back materials are set.

If value is null, then the face material will be set to the default material properties.

The material settings in the GL server will not be changed until update() is called.

See also faceMaterial() and setFaceColor().

void QGLPainter::setLightModel(const QGLLightModel * value)

Sets the current lighting model to value. If value is null, then the default lighting model parameters will be used.

The light settings in the GL server will not be changed until update() is called.

See also lightModel().

void QGLPainter::setMainLight(const QGLLightParameters * parameters)

Sets the parameters for the main light in the scene. The mainLightTransform() is set to the current modelViewMatrix().

Light parameters are stored in world co-ordinates, not eye co-ordinates. The mainLightTransform() specifies the transformation to apply to convert the world co-ordinates into eye co-ordinates when the light is used.

Note: the parameters may be ignored by effect() if it has some other way to determine the lighting conditions.

The light settings in the GL server will not be changed until update() is called.

This function is a convenience that sets the light with identifier 0. If parameters is null, then light 0 will be removed.

See also mainLight(), mainLightTransform(), and addLight().

void QGLPainter::setMainLight(const QGLLightParameters * parameters, const QMatrix4x4 & transform)

Sets the parameters for the main light in the scene, and set mainLightTransform() to transform.

Light parameters are stored in world co-ordinates, not eye co-ordinates. The transform specifies the transformation to apply to convert the world co-ordinates into eye co-ordinates when the light is used.

Note: the parameters may be ignored by effect() if it has some other way to determine the lighting conditions.

The light settings in the GL server will not be changed until update() is called.

This function is a convenience that sets the light with identifier 0. If parameters is null, then light 0 will be removed.

See also mainLight() and mainLightTransform().

void QGLPainter::setObjectPickId(int value)

Sets the current object pick identifier to value. If value is -1, then subsequent objects will be rendered without a pickColor().

If value is not -1, then the pickColor() is changed to a color that represents that object pick identifier. If value has been seen previously, then the same pickColor() as last time will be returned.

The function call will be ignored if isPicking() is false.

See also objectPickId(), clearPickObjects(), and pickObject().

void QGLPainter::setPicking(bool value)

Enables or disables object picking mode according to value.

If value is true, then the effect() will be overridden with a simple flat color effect that renders objects with pickColor(). These colors can be read back later with pickObject().

See also isPicking(), objectPickId(), and pickObject().

void QGLPainter::setScissor(const QRect & rect)

Sets the scissor rect for the current drawing surface to use when GL_SCISSOR_TEST is enabled. If rect is empty, then the scissor will be set to clip away all drawing.

Note that rect is in Qt co-ordinates with the origin at the top-left of the drawing surface's viewport rectangle. If the currentSurface() is an instance of QGLSubsurface, then rect will be adjusted relative to the subsurface's position.

See also currentSurface() and QGLAbstractSurface::viewportGL().

void QGLPainter::setStandardEffect(QGL::StandardEffect effect)

Sets a standard effect to use for rendering fragments in the current GL context. This will also set userEffect() to null. If effect is an invalid value, then the behavior of QGL::FlatColor will be used instead.

See also standardEffect() and setUserEffect().

void QGLPainter::setSurface(QGLAbstractSurface * surface)

Sets the top-most drawing surface on the surface stack to surface and activate it.

Note: if the top-most drawing surface is the main surface specified during begin(), then this function will perform a pushSurface() instead. Typically this function is used to replace the last surface that was pushed onto the stack and avoid doing popSurface() followed by pushSurface(). The main surface cannot be replaced in this manner.

The UpdateViewport flag will be set to indicate that the glViewport() should be adjusted to the extents of surface when update() is next called.

See also pushSurface(), popSurface(), and currentSurface().

void QGLPainter::setUserEffect(QGLAbstractEffect * effect)

Sets a user-defined effect to use for drawing operations in the current GL context. If effect is null, this will disable user-defined effects and return to using standardEffect().

See also userEffect(), effect(), draw(), and setStandardEffect().

void QGLPainter::setVertexAttribute(QGL::VertexAttribute attribute, const QGLAttributeValue & value)

Sets a vertex attribute on the current GL context to value.

The vertex attribute is bound to the GL state on the index corresponding to attribute. For example, QGL::Position will be bound to index 0, QGL::TextureCoord0 will be bound to index 3, etc.

Vertex attributes are independent of the effect() and can be bound once and then used with multiple effects.

If this is the first attribute in a new piece of geometry, it is recommended that clearAttributes() be called before this function. This will inform QGLPainter that a new piece of geometry is being provided and that the previous geometry is now invalid. See the documentation for attributes() for more information.

See also setVertexBundle(), draw(), clearAttributes(), and attributes().

void QGLPainter::setVertexBundle(const QGLVertexBundle & buffer)

Sets the vertex attributes on the current GL context that are stored in buffer.

The vertex attributes are bound to the GL state on the indexes that are specified within buffer; QGL::Position will be bound to index 0, QGL::TextureCoord0 will be bound to index 3, etc.

Vertex attributes are independent of the effect() and can be bound once and then used with multiple effects.

It is recommended that clearAttributes() be called before this function to inform QGLPainter that a new piece of geometry is being provided and that the previous geometry is now invalid. See the documentation for attributes() for more information.

See also setVertexAttribute(), draw(), clearAttributes(), and attributes().

QGL::StandardEffect QGLPainter::standardEffect() const

Returns the standard effect to use for rendering fragments in the current GL context when userEffect() is null.

See also setStandardEffect() and userEffect().

void QGLPainter::update()

Updates the projection matrix, modelview matrix, and lighting conditions in the currently active effect() object by calling QGLAbstractEffect::update(). Also updates glViewport() to cover the currentSurface() if necessary.

Normally this function is called automatically by draw(). However, if the user wishes to use raw GL functions to draw fragments, it will be necessary to explicitly call this function to ensure that the matrix state and lighting conditions have been set on the active effect().

Note that this function informs the effect that an update is needed. It does not change the GL state itself, except for glViewport(). In particular, the modelview and projection matrices in the fixed-function pipeline are not changed unless the effect or application calls updateFixedFunction().

See also setUserEffect(), projectionMatrix(), modelViewMatrix(), draw(), and updateFixedFunction().

void QGLPainter::updateFixedFunction(QGLPainter::Updates updates)

Updates the fixed-function pipeline with the current painting state according to the flags in updates.

This function is intended for use by effects in their QGLAbstractEffect::update() override if they are using the fixed-function pipeline. It can also be used by user applications if they need the QGLPainter state to be set in the fixed-function pipeline.

If the OpenGL implementation does not have a fixed-function pipeline, e.g. OpenGL/ES 2.0, this function does nothing.

See also update().

QGLAbstractEffect * QGLPainter::userEffect() const

Returns the user-defined effect that is being used for drawing operations, or null if standardEffect() is in use.

See also setUserEffect(), standardEffect(), and effect().

QMatrix4x4 QGLPainter::worldMatrix() const

Returns the world matrix, which is the modelViewMatrix() without the eye transformation that was set in the previous call to setCamera().

In the following example, the world variable will be set to the translation and scale component of the modelview transformation, without the "look at" component from the camera:

 painter.setCamera(camera);
 painter.modelViewMatrix().translate(0.0f, 5.0f, 0.0f);
 painter.modelViewMatrix().scale(1.5f);
 QMatrix4x4 world = painter.worldMatrix();

Note: the world matrix is determined by multiplying the inverse of the camera's look at component with the current modelview matrix. Thus, the result may not be precisely the same as constructing a matrix from translate and scale operations starting with the identity.

See also modelViewMatrix() and setCamera().