QSGGeometry Class
La clase QSGGeometry proporciona un almacenamiento de bajo nivel para las primitivas gráficas en el grafo de escena deQt Quick . Más información...
| Encabezado: | #include <QSGGeometry> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
Tipos públicos
| struct | Attribute |
| struct | AttributeSet |
| struct | ColoredPoint2D |
| struct | Point2D |
| struct | TexturedPoint2D |
| enum | AttributeType { UnknownAttribute, PositionAttribute, ColorAttribute, TexCoordAttribute, TexCoord1Attribute, TexCoord2Attribute } |
| enum | DataPattern { AlwaysUploadPattern, DynamicPattern, StaticPattern, StreamPattern } |
| enum | DrawingMode { DrawPoints, DrawLines, DrawLineStrip, DrawTriangles, DrawTriangleStrip } |
| enum | Type { ByteType, UnsignedByteType, ShortType, UnsignedShortType, IntType, …, DoubleType } |
Funciones públicas
| QSGGeometry(const QSGGeometry::AttributeSet &attributes, int vertexCount, int indexCount = 0, int indexType = UnsignedShortType) | |
| virtual | ~QSGGeometry() |
| void | allocate(int vertexCount, int indexCount = 0) |
| int | attributeCount() const |
| const QSGGeometry::Attribute * | attributes() const |
| unsigned int | drawingMode() const |
| int | indexCount() const |
| void * | indexData() |
| const void * | indexData() const |
| uint * | indexDataAsUInt() |
| const uint * | indexDataAsUInt() const |
| quint16 * | indexDataAsUShort() |
| const quint16 * | indexDataAsUShort() const |
| QSGGeometry::DataPattern | indexDataPattern() const |
| int | indexType() const |
| float | lineWidth() const |
| void | markIndexDataDirty() |
| void | markVertexDataDirty() |
| void | setDrawingMode(unsigned int mode) |
(since 6.10) void | setIndexCount(int count) |
| void | setIndexDataPattern(QSGGeometry::DataPattern p) |
| void | setLineWidth(float width) |
(since 6.10) void | setVertexCount(int count) |
| void | setVertexDataPattern(QSGGeometry::DataPattern p) |
| int | sizeOfIndex() const |
| int | sizeOfVertex() const |
| int | vertexCount() const |
| void * | vertexData() |
| const void * | vertexData() const |
| QSGGeometry::ColoredPoint2D * | vertexDataAsColoredPoint2D() |
| const QSGGeometry::ColoredPoint2D * | vertexDataAsColoredPoint2D() const |
| QSGGeometry::Point2D * | vertexDataAsPoint2D() |
| const QSGGeometry::Point2D * | vertexDataAsPoint2D() const |
| QSGGeometry::TexturedPoint2D * | vertexDataAsTexturedPoint2D() |
| const QSGGeometry::TexturedPoint2D * | vertexDataAsTexturedPoint2D() const |
| QSGGeometry::DataPattern | vertexDataPattern() const |
Miembros públicos estáticos
| const QSGGeometry::AttributeSet & | defaultAttributes_ColoredPoint2D() |
| const QSGGeometry::AttributeSet & | defaultAttributes_Point2D() |
| const QSGGeometry::AttributeSet & | defaultAttributes_TexturedPoint2D() |
| void | updateColoredRectGeometry(QSGGeometry *g, const QRectF &rect) |
| void | updateRectGeometry(QSGGeometry *g, const QRectF &rect) |
| void | updateTexturedRectGeometry(QSGGeometry *g, const QRectF &rect, const QRectF &textureRect) |
Descripción detallada
La clase QSGGeometry almacena la geometría de las primitivas renderizadas con el grafo de escena. Contiene datos de vértices y, opcionalmente, datos de índices. El modo utilizado para dibujar la geometría, también denominado «topología de primitivas», se especifica con ` setDrawingMode()`.
Los vértices pueden ser tan simples como puntos definidos por valores x e y, o pueden ser más complejos, de modo que cada vértice contenga una normal, coordenadas de textura y una posición 3D. El ` QSGGeometry::AttributeSet ` se utiliza para describir cómo se construyen los datos de los vértices. El conjunto de atributos solo puede especificarse en el momento de la construcción. La clase `QSGGeometry` proporciona de forma predeterminada algunos atributos y conjuntos de atributos de uso habitual. La función ` defaultAttributes_Point2D()` devuelve un conjunto de atributos que se utilizará en rectángulos sólidos de color normal, mientras que la función ` defaultAttributes_TexturedPoint2D ` devuelve los atributos que se utilizarán para la geometría 2D texturizada. Los datos de vértices se almacenan internamente como un objeto ` void * ` y se puede acceder a ellos mediante la función ` vertexData()`. Se dispone de métodos de acceso de conveniencia para los conjuntos de atributos comunes mediante ` vertexDataAsPoint2D()` y ` vertexDataAsTexturedPoint2D()`. Los datos de vértices se asignan pasando un recuento de vértices al constructor o llamando posteriormente a ` allocate()`.
El número de vértices e índices se puede modificar tras la construcción utilizando el método allocate() para redimensionar el búfer de datos. Sin embargo, allocate() requiere actualizar todos los datos de vértices e índices cada vez que se invoca. Desde Qt 6.10, los métodos setVertexCount() y setIndexCount() permiten ajustar el número de vértices o índices sin reasignar el búfer de datos y solo requieren actualizar los nuevos vértices o índices. En cualquier caso, quien realiza la llamada debe marcar el nodo de geometría como «sucio», llamando a node->markDirty(QSGNode::DirtyGeometry), para garantizar que el renderizador tenga la oportunidad de actualizar los búferes internos.
La QSGGeometry puede contener, opcionalmente, índices de tipo entero sin signo de 32, 16 u 8 bits. El tipo de índice debe especificarse durante la construcción y no puede modificarse.
A continuación se muestra un fragmento de código que ilustra cómo se puede construir una geometría compuesta por vértices de posición y color.
struct MyPoint2D {
float x;
float y;
float r;
float g;
float b;
float a;
void set(float x_, float y_, float r_, float g_, float b_, float a_) {
x = x_;
y = y_;
r = r_;
g = g_;
b = b_;
a = a_;
}
};
QSGGeometry::Attribute MyPoint2D_Attributes[] = {
QSGGeometry::Attribute::create(0, 2, FloatType, true),
QSGGeometry::Attribute::create(1, 4, FloatType, false)
};
QSGGeometry::AttributeSet MyPoint2D_AttributeSet = {
2,
sizeof(MyPoint2D),
MyPoint2D_Attributes
};
...
geometry = new QSGGeometry(MyPoint2D_AttributeSet, 2);
geometry->setDrawingMode(DrawLines);
MyPoint2D *vertices = static_cast<MyPoint2D *>(geometry->vertexData());
vertices[0].set(0, 0, 1, 0, 0, 1);
vertices[1].set(width(), height(), 0, 0, 1, 1);El QSGGeometry es un búfer de software y se encuentra en el lado del cliente en lo que respecta al renderizado acelerado, ya que los búferes utilizados en los gráficos 2D suelen consistir en muchos búferes pequeños que cambian en cada fotograma y no se benefician de ser cargados en la memoria gráfica. No obstante, QSGGeometry admite indicar al renderizador que se debe cargar un búfer mediante las funciones setVertexDataPattern() y setIndexDataPattern(). Que se respete o no esta indicación depende de la implementación.
Nota: Todas las clases con el prefijo QSG deben utilizarse exclusivamente en el hilo de renderizado del grafo de escena. Consulte «Grafo de escena y renderizado» para obtener más información.
Véase también QSGGeometryNode y «Grafo de escena: geometría personalizada».
Documentación sobre tipos de miembros
enum QSGGeometry::AttributeType
Esta enumeración identifica varios tipos de atributos.
| Constante | Valor | Descripción |
|---|---|---|
QSGGeometry::UnknownAttribute | 0 | Indiferente |
QSGGeometry::PositionAttribute | 1 | Posición |
QSGGeometry::ColorAttribute | 2 | Color |
QSGGeometry::TexCoordAttribute | 3 | Coordenada de textura |
QSGGeometry::TexCoord1Attribute | 4 | Coordenada de textura 1 |
QSGGeometry::TexCoord2Attribute | 5 | Coordenada de textura 2 |
enum QSGGeometry::DataPattern
La enumeración DataPattern se utiliza para especificar el patrón de uso de los datos de vértices e índices en un objeto geométrico.
| Constante | Valor | Descripción |
|---|---|---|
QSGGeometry::AlwaysUploadPattern | 0 | Los datos siempre se cargan. Esto significa que el usuario no necesita marcar explícitamente como modificados los datos de índices y vértices tras cambiarlos. Este es el valor predeterminado. |
QSGGeometry::DynamicPattern | 2 | Los datos se modifican repetidamente y se dibujan muchas veces. Se trata de una sugerencia que puede mejorar el rendimiento. Cuando se activa, el usuario debe asegurarse de marcar los datos como modificados tras cambiarlos. |
QSGGeometry::StaticPattern | 3 | Los datos se modifican una vez y se dibujan muchas veces. Se trata de una sugerencia que puede mejorar el rendimiento. Cuando se activa, el usuario debe asegurarse de marcar los datos como modificados tras cambiarlos. |
QSGGeometry::StreamPattern | 1 | Los datos se modifican prácticamente cada vez que se dibujan. Esta sugerencia puede proporcionar un mejor rendimiento. Cuando se activa, el usuario debe asegurarse de marcar los datos como «sucios» después de modificarlos. |
enum QSGGeometry::DrawingMode
Especifica el modo de dibujo, también denominado «topología de primitivas».
Nota: A partir de Qt 6, el grafo de escena solo expone las topologías compatibles con todas las API de gráficos 3D admitidas. Como consecuencia, los valores DrawLineLoop y DrawTriangleFan ya no son compatibles en tiempo de ejecución en Qt 6, aunque los valores de la enumeración en sí sigan estando presentes.
| Constante | Valor |
|---|---|
QSGGeometry::DrawPoints | 0x0000 |
QSGGeometry::DrawLines | 0x0001 |
QSGGeometry::DrawLineStrip | 0x0003 |
QSGGeometry::DrawTriangles | 0x0004 |
QSGGeometry::DrawTriangleStrip | 0x0005 |
enum QSGGeometry::Type
Especifica el tipo de componente en los datos de vértices.
| Constante | Valor | Descripción |
|---|---|---|
QSGGeometry::ByteType | 0x1400 | |
QSGGeometry::UnsignedByteType | 0x1401 | |
QSGGeometry::ShortType | 0x1402 | |
QSGGeometry::UnsignedShortType | 0x1403 | |
QSGGeometry::IntType | 0x1404 | |
QSGGeometry::UnsignedIntType | 0x1405 | |
QSGGeometry::FloatType | 0x1406 | |
QSGGeometry::Bytes2Type | 0x1407 | Incluido en Qt 5.14. |
QSGGeometry::Bytes3Type | 0x1408 | Añadido en Qt 5.14. |
QSGGeometry::Bytes4Type | 0x1409 | Añadido en Qt 5.14. |
QSGGeometry::DoubleType | 0x140A | Añadido en Qt 5.14. |
Documentación de funciones de miembro
QSGGeometry::QSGGeometry(const QSGGeometry::AttributeSet &attributes, int vertexCount, int indexCount = 0, int indexType = UnsignedShortType)
Crea un objeto geométrico basado en attributes.
El objeto asigna espacio para los vértices de vertexCount en función del tamaño acumulado en attributes y para indexCount.
indexType puede ser UnsignedShortType o UnsignedIntType. La compatibilidad con esta última depende de la implementación de la API gráfica utilizada en tiempo de ejecución y puede que no siempre esté disponible.
Los objetos de geometría se crean por defecto con DrawTriangleStrip como modo de dibujo.
Nota: Los objetos« attributes » y « Attribute » a los que hace referencia deben permanecer válidos durante todo el ciclo de vida de «QSGGeometry». «QSGGeometry» almacena una referencia a « attributes » y no elimina los objetos « Attribute ».
[virtual noexcept] QSGGeometry::~QSGGeometry()
Elimina el objeto geométrico y los datos de vértices e índices que este ha asignado.
void QSGGeometry::allocate(int vertexCount, int indexCount = 0)
Reejunta los datos de vértices e índices de este objeto geométrico para que se ajusten a vertexCount vértices y indexCount índices, y establece el número de vértices e índices en consecuencia.
Utiliza setVertexCount() o setIndexCount() para cambiar el número de vértices o índices sin volver a llamar a allocate().
Los datos de vértices e índices quedarán invalidados tras esta llamada y el llamante deberá marcar el nodo de geometría asociado como «sucio», llamando a node->markDirty(QSGNode::DirtyGeometry), para garantizar que el renderizador tenga la oportunidad de actualizar los búferes internos.
Véase también setVertexCount() y setIndexCount().
int QSGGeometry::attributeCount() const
Devuelve el número de atributos del conjunto de atributos utilizado por esta geometría.
const QSGGeometry::Attribute *QSGGeometry::attributes() const
Devuelve un array con los atributos de esta geometría. El tamaño del array viene dado por ` attributeCount()`.
[static] const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_ColoredPoint2D()
Función de conveniencia que devuelve los atributos que se utilizarán para el dibujo en 2D con color por vértice.
[static] const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_Point2D()
Función de conveniencia que devuelve los atributos que se utilizarán para el dibujo en 2D con color sólido.
[static] const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_TexturedPoint2D()
Función de conveniencia que devuelve los atributos que se utilizarán para el dibujo 2D con textura.
unsigned int QSGGeometry::drawingMode() const
Devuelve el modo de dibujo de esta geometría.
El valor por defecto es DrawTriangleStrip.
Véase también setDrawingMode().
int QSGGeometry::indexCount() const
Devuelve el número de índices que se procesan al renderizar el objeto geométrico.
Véase también setIndexCount().
void *QSGGeometry::indexData()
Devuelve un puntero a los datos de índice sin procesar de este objeto geométrico.
Véase también indexDataAsUShort() y indexDataAsUInt().
const void *QSGGeometry::indexData() const
Devuelve un puntero a los datos de índice sin procesar de este objeto geométrico.
Véase también ` indexDataAsUShort()` y ` indexDataAsUInt()`.
uint *QSGGeometry::indexDataAsUInt()
Función de conveniencia para acceder a los datos del índice como una matriz mutable de enteros sin signo de 32 bits.
const uint *QSGGeometry::indexDataAsUInt() const
Función práctica para acceder a los datos del índice como una matriz inmutable de enteros sin signo de 32 bits.
quint16 *QSGGeometry::indexDataAsUShort()
Función práctica para acceder a los datos del índice como una matriz mutable de enteros sin signo de 16 bits.
const quint16 *QSGGeometry::indexDataAsUShort() const
Función práctica para acceder a los datos del índice como una matriz inmutable de enteros sin signo de 16 bits.
QSGGeometry::DataPattern QSGGeometry::indexDataPattern() const
Devuelve el patrón de uso de los índices en esta geometría. El patrón predeterminado es « AlwaysUploadPattern ».
Véase también setIndexDataPattern().
int QSGGeometry::indexType() const
Devuelve el tipo primitivo utilizado para los índices en este objeto geométrico.
float QSGGeometry::lineWidth() const
Obtiene el ancho de línea o el tamaño de punto actuales que se utilizarán para esta geometría. Esta propiedad solo se aplica al ancho de línea cuando el valor de « drawingMode » es « DrawLines » o « DrawLineStrip ». Cuando está disponible, también se aplica al tamaño de punto cuando el valor de « drawingMode » es « DrawPoints ».
El valor por defecto es 1.0
Nota: La compatibilidad con el dibujo de puntos y líneas puede estar limitada en tiempo de ejecución, dependiendo de la plataforma y de la API gráfica. Por ejemplo, algunas API no admiten sprites de puntos, por lo que no es posible establecer un tamaño distinto de 1.
Nota: El ancho de 1.0 siempre es compatible.
Véase también setLineWidth() y drawingMode().
void QSGGeometry::markIndexDataDirty()
Ten en cuenta que los vértices de esta geometría han cambiado y deben volver a cargarse.
Esta función solo surte efecto cuando el patrón de uso de los vértices es «StaticData» y el renderizador que renderiza esta geometría la carga en objetos de búfer de vértices (VBO).
void QSGGeometry::markVertexDataDirty()
Ten en cuenta que los vértices de esta geometría han cambiado y deben volver a cargarse.
Esta función solo surte efecto cuando el patrón de uso de los vértices es «StaticData» y el renderizador que representa esta geometría la carga en objetos de búfer de vértices (VBO).
void QSGGeometry::setDrawingMode(unsigned int mode)
Establece el « mode » que se utilizará para dibujar esta geometría.
El valor por defecto es QSGGeometry::DrawTriangleStrip.
Véase también ` drawingMode()` y ` DrawingMode`.
[since 6.10] void QSGGeometry::setIndexCount(int count)
Establece el número de índices que se procesarán cada vez que se renderice el objeto geométrico.
La función ` count ` no se valida, por lo que es responsabilidad del usuario asegurarse de que solo se especifiquen valores comprendidos entre cero y el número de índices asignados.
Los datos de vértices e índices no se invalidan tras esta llamada, pero quien la realiza debe marcar el nodo de geometría como «sucio», llamando a node->markDirty(QSGNode::DirtyGeometry), para garantizar que el renderizador tenga la oportunidad de actualizar los búferes internos.
Esta función se introdujo en Qt 6.10.
Véase también indexCount().
void QSGGeometry::setIndexDataPattern(QSGGeometry::DataPattern p)
Establece el patrón de uso de los índices en p.
El valor por defecto es ` AlwaysUploadPattern`. Cuando se establece en un valor distinto del predeterminado, el usuario debe llamar a ` markIndexDataDirty()` tras modificar los datos del índice, además de llamar a ` QSGNode::markDirty()` con ` QSGNode::DirtyGeometry`.
Véase también indexDataPattern().
void QSGGeometry::setLineWidth(float width)
Establece el grosor de la línea o el tamaño del punto que se utilizará para esta geometría en width. Esta propiedad solo se aplica al grosor de la línea cuando el valor de « drawingMode » es DrawLines o DrawLineStrip. Cuando está admitido, también se aplica al tamaño del punto cuando el valor de « drawingMode » es DrawPoints.
Nota: La compatibilidad con el dibujo de puntos y líneas puede verse limitada en tiempo de ejecución, dependiendo de la plataforma y de la API gráfica. Por ejemplo, algunas API no admiten sprites de punto, por lo que no es posible establecer un tamaño distinto de 1.
Nota: El ancho de 1.0 siempre es compatible.
Véanse también lineWidth() y drawingMode().
[since 6.10] void QSGGeometry::setVertexCount(int count)
Establece el número de vértices que se van a renderizar.
La función ` count ` no se valida, por lo que es responsabilidad del usuario asegurarse de que solo se especifiquen valores comprendidos entre cero y el número de vértices asignados.
Los datos de los vértices no se invalidan tras esta llamada, pero quien la realiza debe marcar el nodo de geometría como «sucio», llamando a node->markDirty(QSGNode::DirtyGeometry), para garantizar que el renderizador tenga la oportunidad de actualizar los búferes internos.
Esta función se introdujo en Qt 6.10.
Véase también vertexCount().
void QSGGeometry::setVertexDataPattern(QSGGeometry::DataPattern p)
Establece el patrón de uso de los vértices en p.
El valor por defecto es ` AlwaysUploadPattern`. Cuando se establece en un valor distinto del predeterminado, el usuario debe llamar a ` markVertexDataDirty()` tras modificar los datos de los vértices, además de llamar a ` QSGNode::markDirty()` con ` QSGNode::DirtyGeometry`.
Véase también vertexDataPattern().
int QSGGeometry::sizeOfIndex() const
Devuelve el tamaño en bytes del tipo de índice.
Este valor es « 2 » cuando el tipo de índice es « UnsignedShortType », o « 4 » cuando el tipo de índice es « UnsignedIntType ».
int QSGGeometry::sizeOfVertex() const
Devuelve el tamaño, en bytes, de un vértice.
Este valor procede de los atributos.
[static] void QSGGeometry::updateColoredRectGeometry(QSGGeometry *g, const QRectF &rect)
Actualiza la geometría g con las coordenadas de rect.
La función da por hecho que el objeto geométrico contiene una única franja triangular de vértices de QSGGeometry::ColoredPoint2D
[static] void QSGGeometry::updateRectGeometry(QSGGeometry *g, const QRectF &rect)
Actualiza la geometría g con las coordenadas de rect.
La función da por hecho que el objeto geométrico contiene una única franja triangular de vértices de QSGGeometry::Point2D
[static] void QSGGeometry::updateTexturedRectGeometry(QSGGeometry *g, const QRectF &rect, const QRectF &textureRect)
Actualiza la geometría g con las coordenadas de rect y las coordenadas de textura de textureRect.
textureRect Deben ser coordenadas normalizadas.
g Se supone que es una tira de triángulos de cuatro vértices del tipo QSGGeometry::TexturedPoint2D.
int QSGGeometry::vertexCount() const
Devuelve el número de vértices que se pueden renderizar o, si se utilizan índices, devuelve el número de vértices a los que se puede acceder a través de índices.
Véase también ` setVertexCount()`.
void *QSGGeometry::vertexData()
Devuelve un puntero a los datos de vértices sin procesar de este objeto geométrico.
Véase también vertexDataAsPoint2D() y vertexDataAsTexturedPoint2D().
const void *QSGGeometry::vertexData() const
Devuelve un puntero a los datos de vértices sin procesar de este objeto geométrico.
Véase también vertexDataAsPoint2D() y vertexDataAsTexturedPoint2D().
QSGGeometry::ColoredPoint2D *QSGGeometry::vertexDataAsColoredPoint2D()
Función de conveniencia para acceder a los datos de los vértices como una matriz mutable de QSGGeometry::ColoredPoint2D.
const QSGGeometry::ColoredPoint2D *QSGGeometry::vertexDataAsColoredPoint2D() const
Función de conveniencia para acceder a los datos de los vértices como una matriz inmutable de ` QSGGeometry::ColoredPoint2D`.
QSGGeometry::Point2D *QSGGeometry::vertexDataAsPoint2D()
Función de conveniencia para acceder a los datos de los vértices como una matriz mutable de ` QSGGeometry::Point2D`.
const QSGGeometry::Point2D *QSGGeometry::vertexDataAsPoint2D() const
Función de conveniencia para acceder a los datos de los vértices como una matriz inmutable de tipo « QSGGeometry::Point2D ».
QSGGeometry::TexturedPoint2D *QSGGeometry::vertexDataAsTexturedPoint2D()
Función de conveniencia para acceder a los datos de los vértices como una matriz mutable de ` QSGGeometry::TexturedPoint2D`.
const QSGGeometry::TexturedPoint2D *QSGGeometry::vertexDataAsTexturedPoint2D() const
Función de conveniencia para acceder a los datos de los vértices como una matriz inmutable de ` QSGGeometry::TexturedPoint2D`.
QSGGeometry::DataPattern QSGGeometry::vertexDataPattern() const
Devuelve el patrón de uso de los vértices de esta geometría. El patrón por defecto es « AlwaysUploadPattern ».
Véase también setVertexDataPattern().
© 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.