Detailed Description
The QMatrix4x4Stack class manages stacks of transformation matrices in GL applications.
Transformation matrices are one of the basic building blocks of 3D applications, allowing object models to be positioned, scaled, rotated, and projected onto the screen.
GL systems support several standard kinds of matrices, particularly modelview and projection matrices. These matrices are typically organized into stacks, which allow the current matrix state to be saved with push() and restored later with pop().
QMatrix4x4Stack assists QGLPainter with the management of matrix stacks, providing operations to set and modify transformation matrices in each of the standard matrix stacks.
In the following example, a standard orthographic projection matrix for a view is set via the QGLPainter::projectionMatrix() stack, and then a modelview matrix is set via the QGLPainter::modelViewMatrix() stack to scale and translate an object prior to drawing:
QGLPainter painter(this);
QMatrix4x4 projm;
projm.ortho(window->rect());
painter.projectionMatrix() = projm;
painter.modelViewMatrix().setToIdentity();
painter.modelViewMatrix().translate(-1.0f, 2.0f, 0.0f);
painter.modelViewMatrix().scale(0.5f);
Later, the application can save the current modelview matrix state and draw a different object with a different modelview matrix:
painter.modelViewMatrix().push();
painter.modelViewMatrix().setToIdentity();
painter.modelViewMatrix().scale(2.0f);
For efficiency, the matrix values are kept client-side until they are needed by a QGLPainter::draw() operation. Until then, changes to the matrix will not be reflected in the GL server. The application can force the GL server to update the server with a call to QGLPainter::update().
QMatrix4x4Stack is supported on all GL platforms, including OpenGL/ES 2.0 which doesn't support matrix stacks natively. On that platform, the matrix stack is simulated in client memory. When the application selects a shader program to draw under OpenGL/ES 2.0, it calls top() to obtain the actual value to be set on the shader program.
Member Function Documentation
QMatrix4x4Stack::QMatrix4x4Stack()
Creates a matrix stack.
QMatrix4x4Stack::~QMatrix4x4Stack()
Destroy this matrix stack.
bool QMatrix4x4Stack::isDirty() const
Returns true if the top of this matrix stack has been modified; false otherwise.
See also setDirty().
void QMatrix4x4Stack::pop()
Pops the top-most matrix from this matrix stack and sets the current matrix to the next value down. Does nothing if the matrix stack contains a single entry.
See also push().
void QMatrix4x4Stack::push()
Pushes the current matrix onto the matrix stack. The matrix can be restored with pop(). The new top of stack will have the same value as the previous top of stack.
The depths of the traditional GL_MODELVIEW and GL_PROJECTION matrix stacks in the GL server are system-dependent and easy to overflow in nested rendering code using glPushMatrix(). By contrast, the push() function provides an arbitrary-sized stack in client memory.
See also pop() and top().
void QMatrix4x4Stack::rotate(qreal angle, qreal x, qreal y, qreal z)
Multiplies the current matrix at the top of this matrix stack by another that rotates coordinates through angle degrees about the vector (x, y, z). The following example rotates the modelview matrix by 45 degress about the vector (1, -3, 0):
QGLPainter painter(this);
painter.modelViewMatrix().rotate(45.0f, 1.0f, -3.0f, 0.0f);
See also scale() and translate().
void QMatrix4x4Stack::rotate(qreal angle, const QVector3D & vector)
Multiplies the current matrix at the top of this matrix stack by another that rotates coordinates through angle degrees about vector.
See also scale() and translate().
void QMatrix4x4Stack::rotate(const QQuaternion & quaternion)
Multiplies the current matrix at the top of this matrix stack by the quaternion. Thus painter->modelViewMatrix().rotate(quaternion) is equivalent to the following code:
QMatrix4x4 mat;
mat.rotate(quaternion);
painter->modelViewMatrix() *= mat;
which rotates coordinates according to the given quaternion.
See also scale() and translate().
void QMatrix4x4Stack::scale(qreal x, qreal y, qreal z)
Multiplies the current matrix at the top of this matrix stack by another that scales coordinates by the components x, y, and z. The following example scales the modelview matrix by (1, 2, 1):
QGLPainter painter(this);
painter.modelViewMatrix().scale(1.0f, 2.0f, 1.0f);
See also translate() and rotate().
void QMatrix4x4Stack::scale(qreal factor)
Multiplies the current matrix at the top of this matrix stack by another that scales coordinates by the given factor. The following example scales the modelview matrix by a factor of 2:
QGLPainter painter(this);
painter.modelViewMatrix().scale(2.0f);
See also translate() and rotate().
void QMatrix4x4Stack::scale(const QVector3D & vector)
Multiplies the current matrix at the top of this matrix stack by another that scales coordinates by the components of vector.
See also translate() and rotate().
void QMatrix4x4Stack::setDirty(bool dirty)
Sets the dirty flag on this matrix stack, which indicates if it has been modified.
A matrix stack may also be set to dirty by translate(), scale(), operator*(), etc.
See also isDirty().
void QMatrix4x4Stack::setToIdentity()
Set the matrix at the top of this matrix stack to the identity matrix.
See also operator=().
const QMatrix4x4 & QMatrix4x4Stack::top() const
Returns a const reference to the current matrix at the top of this matrix stack. This is typically used to fetch the matrix so it can be set on user-defined shader programs.
See also operator=().
void QMatrix4x4Stack::translate(qreal x, qreal y, qreal z)
Multiplies the current matrix at the top of this matrix stack by another that translates coordinates by (x, y, z). The following example translates the modelview matrix by (1, -3, 0):
QGLPainter painter(this);
painter.modelViewMatrix().translate(1.0f, -3.0f, 0.0f);
See also scale() and rotate().
void QMatrix4x4Stack::translate(const QVector3D & vector)
Multiplies the current matrix at the top of this matrix statck by another that translates coordinates by the components of vector.
See also scale() and rotate().
QMatrix4x4Stack::operator const QMatrix4x4 &() const
Returns a const reference to the current matrix at the top of this matrix stack.
See also top().
QMatrix4x4Stack & QMatrix4x4Stack::operator*=(const QMatrix4x4 & matrix)
Multiplies the matrix at the top of this matrix stack by matrix.
See also top().
QMatrix4x4Stack & QMatrix4x4Stack::operator=(const QMatrix4x4 & matrix)
Assigns matrix to the matrix at the top of this matrix stack.
See also top().
