En esta página

QMatrix4x4 Class

La clase QMatrix4x4 representa una matriz de transformación 4x4 en el espacio 3D. Más información...

Encabezado: #include <QMatrix4x4>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

Funciones públicas

QMatrix4x4()
QMatrix4x4(const QGenericMatrix<N, M, float> &matrix)
QMatrix4x4(const QTransform &transform)
QMatrix4x4(const float *values)
QMatrix4x4(float m11, float m12, float m13, float m14, float m21, float m22, float m23, float m24, float m31, float m32, float m33, float m34, float m41, float m42, float m43, float m44)
QVector4D column(int index) const
const float *constData() const
void copyDataTo(float *values) const
float *data()
const float *data() const
double determinant() const
void fill(float value)
void frustum(float left, float right, float bottom, float top, float nearPlane, float farPlane)
QMatrix4x4 inverted(bool *invertible = nullptr) const
bool isAffine() const
bool isIdentity() const
void lookAt(const QVector3D &eye, const QVector3D &center, const QVector3D &up)
QPoint map(const QPoint &point) const
QPointF map(const QPointF &point) const
QVector3D map(const QVector3D &point) const
QVector4D map(const QVector4D &point) const
QRect mapRect(const QRect &rect) const
QRectF mapRect(const QRectF &rect) const
QVector3D mapVector(const QVector3D &vector) const
QMatrix3x3 normalMatrix() const
void optimize()
void ortho(float left, float right, float bottom, float top, float nearPlane, float farPlane)
void ortho(const QRect &rect)
void ortho(const QRectF &rect)
void perspective(float verticalAngle, float aspectRatio, float nearPlane, float farPlane)
void rotate(const QQuaternion &quaternion)
void rotate(float angle, const QVector3D &vector)
void rotate(float angle, float x, float y, float z = 0.0f)
QVector4D row(int index) const
void scale(const QVector3D &vector)
void scale(float factor)
void scale(float x, float y)
void scale(float x, float y, float z)
void setColumn(int index, const QVector4D &value)
void setRow(int index, const QVector4D &value)
void setToIdentity()
QGenericMatrix<N, M, float> toGenericMatrix() const
QTransform toTransform() const
QTransform toTransform(float distanceToPlane) const
void translate(const QVector3D &vector)
void translate(float x, float y)
void translate(float x, float y, float z)
QMatrix4x4 transposed() const
void viewport(float left, float bottom, float width, float height, float nearPlane = 0.0f, float farPlane = 1.0f)
void viewport(const QRectF &rect)
operator QVariant() const
bool operator!=(const QMatrix4x4 &other) const
float &operator()(int row, int column)
const float &operator()(int row, int column) const
QMatrix4x4 &operator*=(const QMatrix4x4 &other)
QMatrix4x4 &operator*=(float factor)
QMatrix4x4 &operator+=(const QMatrix4x4 &other)
QMatrix4x4 &operator-=(const QMatrix4x4 &other)
QMatrix4x4 &operator/=(float divisor)
bool operator==(const QMatrix4x4 &other) const
bool qFuzzyCompare(const QMatrix4x4 &m1, const QMatrix4x4 &m2)
QMatrix4x4 operator*(const QMatrix4x4 &m1, const QMatrix4x4 &m2)
QVector4D operator*(const QMatrix4x4 &matrix, const QVector4D &vector)
QMatrix4x4 operator*(const QMatrix4x4 &matrix, float factor)
QPoint operator*(const QPoint &point, const QMatrix4x4 &matrix)
QPointF operator*(const QPointF &point, const QMatrix4x4 &matrix)
QVector4D operator*(const QVector4D &vector, const QMatrix4x4 &matrix)
QMatrix4x4 operator*(float factor, const QMatrix4x4 &matrix)
QMatrix4x4 operator+(const QMatrix4x4 &m1, const QMatrix4x4 &m2)
QMatrix4x4 operator-(const QMatrix4x4 &m1, const QMatrix4x4 &m2)
QMatrix4x4 operator-(const QMatrix4x4 &matrix)
QMatrix4x4 operator/(const QMatrix4x4 &matrix, float divisor)
QDataStream &operator<<(QDataStream &stream, const QMatrix4x4 &matrix)
QDataStream &operator>>(QDataStream &stream, QMatrix4x4 &matrix)

Descripción detallada

La clase QMatrix4x4 se trata, en general, como una matriz con orden de filas, en el sentido de que los constructores y las funciones operator() aceptan datos en formato de orden de filas, tal y como es habitual en el estilo de programación C.

Internamente, los datos se almacenan en formato «column-major», para que el paso de datos a las funciones de OpenGL —que esperan datos en este formato— resulte óptimo.

Al utilizar estas funciones, hay que tener en cuenta que devuelven datos en formato «column-major »:

Véase también QVector3D y QGenericMatrix.

Documentación de las funciones miembro

QMatrix4x4::QMatrix4x4()

Crea una matriz identidad.

[explicit] template <int N, int M> QMatrix4x4::QMatrix4x4(const QGenericMatrix<N, M, float> &matrix)

Crea una matriz de 4x4 a partir de las 4 columnas más a la izquierda y las 4 filas superiores de matrix. Si matrix tiene menos de 4 columnas o filas, los elementos restantes se rellenan con elementos de la matriz identidad.

Véase también toGenericMatrix().

QMatrix4x4::QMatrix4x4(const QTransform &transform)

Crea una matriz de 4x4 a partir de la matriz de transformación 2D convencional de Qt XML transform.

Si transform tiene un tipo especial (identidad, traslación, escala, etc.), el programador debe seguir este constructor con una llamada a optimize() si desea que QMatrix4x4 optimice las llamadas posteriores a translate(), scale(), etc.

Véanse también toTransform() y optimize().

[explicit] QMatrix4x4::QMatrix4x4(const float *values)

Crea una matriz a partir de los 16 valores de punto flotante proporcionados values. Se da por hecho que el contenido de la matriz values está ordenado por filas.

Si la matriz tiene un tipo especial (identidad, traslación, escala, etc.), el programador debe seguir este constructor con una llamada a optimize() si desea que QMatrix4x4 optimice las llamadas posteriores a translate(), scale(), etc.

Véanse también copyDataTo() y optimize().

QMatrix4x4::QMatrix4x4(float m11, float m12, float m13, float m14, float m21, float m22, float m23, float m24, float m31, float m32, float m33, float m34, float m41, float m42, float m43, float m44)

Crea una matriz a partir de los 16 elementos m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43 y m44. Los elementos se especifican en orden de filas.

Si la matriz tiene un tipo especial (identidad, traslación, escala, etc.), el programador debe seguir este constructor con una llamada a ` optimize()` si desea que `QMatrix4x4` optimice las llamadas posteriores a ` translate()`, ` scale()`, etc.

Véase también ` optimize()`.

QVector4D QMatrix4x4::column(int index) const

Devuelve los elementos de la columna « index » como un vector 4D.

Véase también ` setColumn()` y ` row()`.

const float *QMatrix4x4::constData() const

Devuelve un puntero constante a los datos sin procesar de esta matriz. Estos datos sin procesar se almacenan en formato por columnas.

Véase también data().

void QMatrix4x4::copyDataTo(float *values) const

Recupera los 16 elementos de esta matriz y los copia a « values » en orden de filas.

float *QMatrix4x4::data()

Devuelve un puntero a los datos sin procesar de esta matriz.

Véase también constData() y optimize().

const float *QMatrix4x4::data() const

Devuelve un puntero constante a los datos sin procesar de esta matriz. Estos datos sin procesar se almacenan en formato «column-major».

Véase también constData().

double QMatrix4x4::determinant() const

Devuelve el determinante de esta matriz.

void QMatrix4x4::fill(float value)

Rellena todos los elementos de esta matriz con « value ».

void QMatrix4x4::frustum(float left, float right, float bottom, float top, float nearPlane, float farPlane)

Multiplica esta matriz por otra que aplica una proyección en forma de frustum en perspectiva para una ventana cuya esquina inferior izquierda es (left, bottom), cuya esquina superior derecha es (right, top) y cuyos planos de recorte especificados son nearPlane y farPlane.

Véase también ortho() y perspective().

QMatrix4x4 QMatrix4x4::inverted(bool *invertible = nullptr) const

Devuelve la inversa de esta matriz. Devuelve la matriz identidad si esta matriz no puede invertirse; es decir, si ` determinant()` es cero. Si ` invertible ` no es nulo, se escribirá «true» en esa posición si la matriz puede invertirse; en caso contrario, se escribirá «false».

Si la matriz se reconoce como la matriz identidad o como una matriz ortonormal, esta función invertirá rápidamente la matriz utilizando rutinas optimizadas.

Véanse también determinant() y normalMatrix().

bool QMatrix4x4::isAffine() const

Devuelve « true » si esta matriz es afín; en caso contrario, devuelve «false».

Una matriz afín es una matriz de 4x4 cuya tercera fila es igual a (0, 0, 0, 1), es decir, que no tiene coeficientes proyectivos.

Véase también isIdentity().

bool QMatrix4x4::isIdentity() const

Devuelve ` true ` si esta matriz es la identidad; en caso contrario, devuelve `false`.

Véase también setToIdentity().

void QMatrix4x4::lookAt(const QVector3D &eye, const QVector3D &center, const QVector3D &up)

Multiplica esta matriz por una matriz de visión derivada de un punto ocular. El valor center indica el centro de la vista hacia la que mira el eye. El valor up indica qué dirección debe considerarse «arriba» con respecto al eye.

Nota: El vector up no debe ser paralelo a la línea de visión desde eye hasta center.

QPoint QMatrix4x4::map(const QPoint &point) const

Asigna point multiplicando esta matriz por point. La matriz se aplica antes de cada punto.

Véase también mapRect().

QPointF QMatrix4x4::map(const QPointF &point) const

Asigna point multiplicando por la derecha esta matriz por point. La matriz se aplica antes del punto.

Véase también mapRect().

QVector3D QMatrix4x4::map(const QVector3D &point) const

Asigna « point » multiplicando esta matriz por point, ampliada a un vector de 4 dimensiones al asignar el valor 1,0 a la coordenada w. La matriz se aplica antes del punto.

Nota: Esta función no es la misma que mapVector(). Para puntos, utiliza siempre map(). mapVector() solo es adecuada para vectores (direcciones).

Véanse también mapRect() y mapVector().

QVector4D QMatrix4x4::map(const QVector4D &point) const

Asigna point multiplicando esta matriz por point. La matriz se aplica antes de cada punto.

Véase también mapRect().

QRect QMatrix4x4::mapRect(const QRect &rect) const

Asigna rect multiplicando esta matriz por los vértices de rect y, a continuación, formando un nuevo rectángulo a partir de los resultados. El rectángulo devuelto será un rectángulo 2D normal con los lados paralelos a los ejes horizontal y vertical.

Véase también map().

QRectF QMatrix4x4::mapRect(const QRectF &rect) const

Asigna rect multiplicando esta matriz por los vértices de rect y, a continuación, formando un nuevo rectángulo a partir de los resultados. El rectángulo devuelto será un rectángulo 2D normal con los lados paralelos a los ejes horizontal y vertical.

Véase también map().

QVector3D QMatrix4x4::mapVector(const QVector3D &vector) const

Asigna vector multiplicando la parte superior de 3x3 de esta matriz por vector. Se ignoran los componentes de traslación y proyección de esta matriz. La matriz se aplica como un vector previo.

Véase también map().

QMatrix3x3 QMatrix4x4::normalMatrix() const

Devuelve la matriz normal correspondiente a esta transformación 4x4. La matriz normal es la transpuesta de la inversa de la parte superior izquierda de 3x3 de esta matriz 4x4. Si la submatriz 3x3 no es invertible, esta función devuelve la matriz identidad.

Véase también inverted().

void QMatrix4x4::optimize()

Optimiza el uso de esta matriz a partir de sus elementos actuales.

Algunas operaciones, como translate(), scale() y rotate(), pueden realizarse de forma más eficiente si ya se sabe que la matriz que se va a modificar es la identidad, un resultado anterior de translate(), un resultado anterior de scale(), etc.

Normalmente, la clase QMatrix4x4 lleva un registro interno de este tipo especial a medida que se realizan las operaciones. Sin embargo, si la matriz se modifica directamente con operator()(int, int) o data(), entonces QMatrix4x4 perderá el rastro del tipo especial y, a partir de ese momento, volverá a realizar las operaciones más seguras, aunque menos eficientes.

Al llamar a `optimize()` tras modificar directamente la matriz, el programador puede obligar a ` QMatrix4x4 ` a recuperar el tipo especial si los elementos parecen ajustarse a uno de los tipos optimizados conocidos.

Véanse también operator()(int, int), data() y translate().

void QMatrix4x4::ortho(float left, float right, float bottom, float top, float nearPlane, float farPlane)

Multiplica esta matriz por otra que aplica una proyección ortográfica para una ventana cuya esquina inferior izquierda se encuentra en (left, bottom), cuya esquina superior derecha se encuentra en (right, top) y cuyos planos de recorte especificados son nearPlane y farPlane.

Véase también frustum() y perspective().

void QMatrix4x4::ortho(const QRect &rect)

Multiplica esta matriz por otra que aplica una proyección ortográfica a una ventana cuyos límites se especifican mediante rect. Los planos de recorte cercano y lejano serán -1 y 1, respectivamente.

Esta es una función sobrecargada.

Véanse también frustum() y perspective().

void QMatrix4x4::ortho(const QRectF &rect)

Multiplica esta matriz por otra que aplica una proyección ortográfica para una ventana cuyos límites vienen especificados por rect. Los planos de recorte cercano y lejano serán -1 y 1, respectivamente.

Esta es una función sobrecargada.

Véase también frustum() y perspective().

void QMatrix4x4::perspective(float verticalAngle, float aspectRatio, float nearPlane, float farPlane)

Multiplica esta matriz por otra que aplica una proyección en perspectiva. El campo de visión vertical será de verticalAngle grados dentro de una ventana con un aspectRatio determinado que establece el campo de visión horizontal. La proyección tendrá los planos de recorte especificados nearPlane y farPlane, que son las distancias desde el observador hasta los planos correspondientes.

Véase también ortho() y frustum().

void QMatrix4x4::rotate(const QQuaternion &quaternion)

Multiplica esta matriz por otra que gira las coordenadas según una rotación especificada quaternion. Se supone que la matriz de rotación quaternion ha sido normalizada.

Véanse también scale(), translate() y QQuaternion.

void QMatrix4x4::rotate(float angle, const QVector3D &vector)

Multiplica esta matriz por otra que gira las coordenadas angle grados alrededor de vector.

Véase también scale() y translate().

void QMatrix4x4::rotate(float angle, float x, float y, float z = 0.0f)

Multiplica esta matriz por otra que gira las coordenadas un ángulo de angle grados alrededor del vector (x, y, z).

Esta es una función sobrecargada.

Véanse también scale() y translate().

QVector4D QMatrix4x4::row(int index) const

Devuelve los elementos de la fila « index » como un vector 4D.

Véase también setRow() y column().

void QMatrix4x4::scale(const QVector3D &vector)

Multiplica esta matriz por otra que escala las coordenadas según los componentes de vector.

Véanse también translate() y rotate().

void QMatrix4x4::scale(float factor)

Multiplica esta matriz por otra que escala las coordenadas según el valor dado factor.

Esta es una función sobrecargada.

Véanse también translate() y rotate().

void QMatrix4x4::scale(float x, float y)

Multiplica esta matriz por otra que escala las coordenadas por los componentes x y y.

Esta es una función sobrecargada.

Véanse también translate() y rotate().

void QMatrix4x4::scale(float x, float y, float z)

Multiplica esta matriz por otra que escala las coordenadas por los componentes x, y y z.

Esta es una función sobrecargada.

Véanse también translate() y rotate().

void QMatrix4x4::setColumn(int index, const QVector4D &value)

Establece los elementos de la columna index como los componentes de value.

Véase también column() y setRow().

void QMatrix4x4::setRow(int index, const QVector4D &value)

Establece los elementos de la fila index como los componentes de value.

Véase también row() y setColumn().

void QMatrix4x4::setToIdentity()

Establece esta matriz como la identidad.

Véase también isIdentity().

template <int N, int M> QGenericMatrix<N, M, float> QMatrix4x4::toGenericMatrix() const

Crea una matriz genérica de tamaño N x M a partir de las N columnas más a la izquierda y las M filas más arriba de esta matriz de 4x4. Si N o M es mayor que 4, los elementos restantes se rellenan con elementos de la matriz identidad.

QTransform QMatrix4x4::toTransform() const

Devuelve la matriz de transformación 2D convencional de Qt que se corresponde con esta matriz.

La matriz ` QTransform ` devuelta se obtiene simplemente eliminando la tercera fila y la tercera columna de la matriz ` QMatrix4x4`. Esto resulta adecuado para implementar proyecciones ortográficas en las que la coordenada z debe eliminarse en lugar de proyectarse.

QTransform QMatrix4x4::toTransform(float distanceToPlane) const

Devuelve la matriz de transformación 2D convencional de Qt que se corresponde con esta matriz.

Si distanceToPlane es distinto de cero, indica un factor de proyección que se debe utilizar para ajustar la coordenada z. El valor 1024 corresponde al factor de proyección utilizado por QTransform::rotate() para los ejes x e y.

Si distanceToPlane es cero, la matriz QTransform devuelta se forma simplemente omitiendo la tercera fila y la tercera columna de la matriz QMatrix4x4. Esto resulta adecuado para implementar proyecciones ortográficas en las que la coordenada z debe omitirse en lugar de proyectarse.

void QMatrix4x4::translate(const QVector3D &vector)

Multiplica esta matriz por otra que traslada las coordenadas según los componentes de vector.

Véase también scale() y rotate().

void QMatrix4x4::translate(float x, float y)

Multiplica esta matriz por otra que traslada las coordenadas según los componentes x y y.

Esta es una función sobrecargada.

Véanse también scale() y rotate().

void QMatrix4x4::translate(float x, float y, float z)

Multiplica esta matriz por otra que traslada las coordenadas en las componentes x, y y z.

Esta es una función sobrecargada.

Véanse también scale() y rotate().

QMatrix4x4 QMatrix4x4::transposed() const

Devuelve esta matriz transpuesta respecto a su diagonal.

void QMatrix4x4::viewport(float left, float bottom, float width, float height, float nearPlane = 0.0f, float farPlane = 1.0f)

Multiplica esta matriz por otra que realiza la transformación de escala y desplazamiento utilizada por OpenGL para pasar de coordenadas normalizadas del dispositivo (NDC) a coordenadas de la ventana gráfica (viewport). Es decir, mapea los puntos del cubo, que varían entre [-1, 1] en cada dimensión, a la ventana de visualización, cuya esquina inferior izquierda más cercana se encuentra en (left, bottom, nearPlane) y cuyo tamaño es (width, height, farPlane - nearPlane).

Esto se corresponde con la transformación utilizada por la transformación de la ventana gráfica de OpenGL de función fija, controlada por las funciones glViewport() y glDepthRange().

void QMatrix4x4::viewport(const QRectF &rect)

Configura la transformación de la ventana de visualización para una ventana delimitada por rect y con los valores de «near» y «far» establecidos en 0 y 1, respectivamente.

Esta es una función sobrecargada.

QMatrix4x4::operator QVariant() const

Devuelve la matriz como un objeto de tipo « QVariant ».

bool QMatrix4x4::operator!=(const QMatrix4x4 &other) const

Devuelve « true » si esta matriz no es idéntica a « other »; en caso contrario, devuelve «false». Este operador utiliza una comparación exacta en coma flotante.

float &QMatrix4x4::operator()(int row, int column)

Devuelve una referencia al elemento situado en la posición (row, column) de esta matriz, de modo que se pueda asignar un valor a dicho elemento.

Véanse también optimize(), setColumn() y setRow().

const float &QMatrix4x4::operator()(int row, int column) const

Devuelve una referencia constante al elemento situado en la posición (row, column) de esta matriz.

Véanse también column() y row().

QMatrix4x4 &QMatrix4x4::operator*=(const QMatrix4x4 &other)

Multiplica el contenido de ` other ` por esta matriz.

QMatrix4x4 &QMatrix4x4::operator*=(float factor)

Multiplica todos los elementos de esta matriz por factor.

Esta es una función sobrecargada.

QMatrix4x4 &QMatrix4x4::operator+=(const QMatrix4x4 &other)

Añade el contenido de « other » a esta matriz.

QMatrix4x4 &QMatrix4x4::operator-=(const QMatrix4x4 &other)

Resta el contenido de other de esta matriz.

QMatrix4x4 &QMatrix4x4::operator/=(float divisor)

Divide todos los elementos de esta matriz entre divisor.

bool QMatrix4x4::operator==(const QMatrix4x4 &other) const

Devuelve « true » si esta matriz es idéntica a « other »; en caso contrario, devuelve «false». Este operador utiliza una comparación exacta en coma flotante.

Elementos no miembros relacionados

[noexcept] bool qFuzzyCompare(const QMatrix4x4 &m1, const QMatrix4x4 &m2)

Devuelve « true » si « m1 » y « m2 » son iguales, teniendo en cuenta un pequeño margen de imprecisión en las comparaciones de números de coma flotante; en caso contrario, devuelve «false».

QMatrix4x4 operator*(const QMatrix4x4 &m1, const QMatrix4x4 &m2)

Devuelve el producto de m1 y m2.

QVector4D operator*(const QMatrix4x4 &matrix, const QVector4D &vector)

Devuelve el resultado de la transformación de vector según matrix, con la matriz aplicada al vector inicial.

QMatrix4x4 operator*(const QMatrix4x4 &matrix, float factor)

Devuelve el resultado de multiplicar todos los elementos de ` matrix ` por ` factor`.

QPoint operator*(const QPoint &point, const QMatrix4x4 &matrix)

Devuelve el resultado de la transformación de point según matrix, aplicando la matriz tras el punto.

QPointF operator*(const QPointF &point, const QMatrix4x4 &matrix)

Devuelve el resultado de transformar point según matrix, aplicando la matriz tras el punto.

QVector4D operator*(const QVector4D &vector, const QMatrix4x4 &matrix)

Devuelve el resultado de la transformación de vector según matrix, aplicando la matriz después del vector.

QMatrix4x4 operator*(float factor, const QMatrix4x4 &matrix)

Devuelve el resultado de multiplicar todos los elementos de ` matrix ` por ` factor`.

QMatrix4x4 operator+(const QMatrix4x4 &m1, const QMatrix4x4 &m2)

Devuelve la suma de m1 y m2.

QMatrix4x4 operator-(const QMatrix4x4 &m1, const QMatrix4x4 &m2)

Devuelve la diferencia entre m1 y m2.

QMatrix4x4 operator-(const QMatrix4x4 &matrix)

Devuelve la negación de ` matrix`.

Esta es una función sobrecargada.

QMatrix4x4 operator/(const QMatrix4x4 &matrix, float divisor)

Devuelve el resultado de dividir todos los elementos de ` matrix ` entre ` divisor`.

QDataStream &operator<<(QDataStream &stream, const QMatrix4x4 &matrix)

Escribe el objeto ` matrix ` especificado en el objeto ` stream ` especificado y devuelve una referencia al flujo.

Véase también «Serialización detipos de datos de Qt».

QDataStream &operator>>(QDataStream &stream, QMatrix4x4 &matrix)

Lee una matriz de 4x4 desde el archivo stream especificado y la escribe en el archivo matrix especificado, y devuelve una referencia al flujo.

Véase también «Serialización detipos de datos de Qt».

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.