QQuick3DGeometry Class
Clase base para definir geometría personalizada. Más...
| Header: | #include <QQuick3DGeometry> |
| In QML: | Geometry |
| Inherits: | QQuick3DObject |
Funciones públicas
| void | addAttribute(QQuick3DGeometry::Attribute::Semantic semantic, int offset, QQuick3DGeometry::Attribute::ComponentType componentType) |
| void | addAttribute(const QQuick3DGeometry::Attribute &attribute) |
| void | addSubset(int offset, int count, const QVector3D &boundsMin, const QVector3D &boundsMax, const QString &name = {}) |
(since 6.6) void | addTargetAttribute(quint32 targetId, QQuick3DGeometry::Attribute::Semantic semantic, int offset, int stride = 0) |
(since 6.6) void | addTargetAttribute(const QQuick3DGeometry::TargetAttribute &attribute) |
| QQuick3DGeometry::Attribute | attribute(int index) const |
| int | attributeCount() const |
| QVector3D | boundsMax() const |
| QVector3D | boundsMin() const |
| void | clear() |
| QByteArray | indexData() const |
| QQuick3DGeometry::PrimitiveType | primitiveType() const |
| void | setBounds(const QVector3D &min, const QVector3D &max) |
| void | setIndexData(const QByteArray &data) |
| void | setIndexData(int offset, const QByteArray &data) |
| void | setPrimitiveType(QQuick3DGeometry::PrimitiveType type) |
| void | setStride(int stride) |
(since 6.6) void | setTargetData(const QByteArray &data) |
(since 6.6) void | setTargetData(int offset, const QByteArray &data) |
| void | setVertexData(const QByteArray &data) |
| void | setVertexData(int offset, const QByteArray &data) |
| int | stride() const |
| QVector3D | subsetBoundsMax(int subset) const |
| QVector3D | subsetBoundsMin(int subset) const |
| int | subsetCount() const |
| int | subsetCount(int subset) const |
| QString | subsetName(int subset) const |
| int | subsetOffset(int subset) const |
(since 6.6) QQuick3DGeometry::TargetAttribute | targetAttribute(int index) const |
(since 6.6) int | targetAttributeCount() const |
(since 6.6) QByteArray | targetData() const |
| QByteArray | vertexData() const |
Descripción detallada
La clase `QQuick3DGeometry` se puede utilizar para especificar una geometría personalizada para un modelo en la escena 3D de ` Qt Quick `.
Aunque no es estrictamente necesario, lo habitual es heredar de esta clase. A continuación, la subclase se expone a QML registrándola en el sistema de tipos. La propiedad ` geometry ` de un modelo puede entonces configurarse para que haga referencia a una instancia del tipo registrado.
La estructura general de una clase de este tipo suele ser similar a la siguiente:
class CustomGeometry : public QQuick3DGeometry
{
public:
CustomGeometry() { rebuildGeometry(); }
void setSomething() {
// Change relevant internal data.
// ...
// Then rebuild the vertex and index data and pass it to QQuick3DGeometry.
rebuildGeometry();
// Finally, trigger an update. This is relevant in case nothing else
// is changing in the scene; this way we make sure a new frame will
// be rendered.
update();
}
private:
void rebuildGeometry()
{
QByteArray vertices;
QByteArray indices;
...
setPrimitiveType(Lines);
setVertexBuffer(vertices);
setIndexBuffer(indices);
setStride(3 * sizeof(float)); // e.g. when having 3 components per vertex
setBounds(...); // minimum and maximum extents, for picking
addAttribute(PositionSemantic, 0, F32Type);
...
}
};A continuación, esta clase se puede registrar como un tipo de QML y utilizarse con Model.
En Qt 5, el registro de tipos se realizaba mediante ` qmlRegisterType`:
qmlRegisterType<CustomGeometry>("Example", 1, 0, "CustomGeometry");En Qt 6, el enfoque predeterminado es utilizar el registro automático con la ayuda del sistema de compilación. En lugar de llamar a ` qmlRegisterType`, el archivo ` .pro ` puede contener ahora:
CONFIG += qmltypes
QML_IMPORT_NAME = Example
QML_IMPORT_MAJOR_VERSION = 1Con CMake, el registro automático es el comportamiento predeterminado, por lo que no se necesitan configuraciones especiales más allá de la configuración básica del módulo QML:
qt_add_qml_module(application
URI Example
VERSION 1.0
)La implementación de la clase debe añadir ` QML_NAMED_ELEMENT`:
class CustomGeometry : public QQuick3DGeometry
{
Q_OBJECT
QML_NAMED_ELEMENT(CustomGeometry)
...
};A continuación, el código QML puede utilizar el tipo personalizado:
import Example 1.0
Model {
id: customModel
geometry: CustomGeometry {
}
}Como mínimo, una geometría personalizada debe tener especificado lo siguiente:
- datos de vértices,
- paso de vértices,
- tipo de primitiva,
- un atributo con PositionSemantic.
Esto es suficiente para renderizar la malla. Para el dibujo indexado, también es necesario especificar los datos del búfer de índices y un atributo con «IndexSemantic». Para que sea compatible con la selección (entrada), la clase debe especificar el volumen delimitador mediante « setBounds()». Para una iluminación adecuada, se necesita un atributo con «NormalSemantic». Cuando el material utiliza texturas, debe proporcionarse al menos un conjunto de coordenadas UV y describirse en un atributo «TexCoord0Semantic» o «TexCoord1Semantic». Algunos materiales pueden requerir también tangentes y binormales.
A modo de ejemplo concreto y mínimo, la siguiente clase proporcionaría la geometría de un único triángulo:
class ExampleGeometry : public QQuick3DGeometry
{
Q_OBJECT
QML_NAMED_ELEMENT(ExampleGeometry)
public:
ExampleGeometry();
private:
void updateData();
};
ExampleGeometry::ExampleGeometry()
{
updateData();
}
void ExampleGeometry::updateData()
{
QByteArray v;
v.resize(3 * 3 * sizeof(float));
float *p = reinterpret_cast<float *>(v.data());
// a triangle, front face = counter-clockwise
*p++ = -1.0f; *p++ = -1.0f; *p++ = 0.0f;
*p++ = 1.0f; *p++ = -1.0f; *p++ = 0.0f;
*p++ = 0.0f; *p++ = 1.0f; *p++ = 0.0f;
setVertexData(v);
setStride(3 * sizeof(float));
setPrimitiveType(QQuick3DGeometry::PrimitiveType::Triangles);
addAttribute(QQuick3DGeometry::Attribute::PositionSemantic,
0,
QQuick3DGeometry::Attribute::F32Type);
}Dependiendo de la iluminación de la escena, el resultado de hacer referencia a esta geometría desde un Model:

Nota: Se espera que los datosde vértices sigan las convenciones de OpenGL. Esto significa que los datos deben proporcionarse partiendo de la premisa de que el eje Y apunta hacia arriba en el sistema de coordenadas normalizado del dispositivo, y que las caras frontales tienen un enrollamiento en sentido antihorario.
Véase también Model y Geometry.
Documentación de las funciones miembro
void QQuick3DGeometry::addAttribute(QQuick3DGeometry::Attribute::Semantic semantic, int offset, QQuick3DGeometry::Attribute::ComponentType componentType)
Añade la descripción de los atributos de los vértices. Cada atributo tiene una « semantic », que especifica el uso del atributo y el número de componentes que tiene; una « offset », que indica la ubicación del atributo dentro del vértice; y una « componentType », que especifica el tipo de datos y el tamaño del atributo.
La semántica puede ser una de las siguientes:
| Constante | Descripción |
|---|---|
PositionSemantic | El atributo es una posición. 3 componentes: x, y y z |
NormalSemantic | El atributo es un vector normal. 3 componentes: x, y y z |
TexCoord0Semantic | El atributo es una coordenada de textura. 2 componentes: u y v |
TexCoord1Semantic | El atributo es una coordenada de textura. 2 componentes: u y v |
TangentSemantic | El atributo es un vector tangente. 3 componentes: x, y y z |
BinormalSemantic | El atributo es un vector binormal. 3 componentes: x, y y z |
JointSemantic | El atributo es un vector de índice de articulación para el skinning. 4 componentes: índice de articulación 1-4 |
WeightSemantic | El atributo es un vector de peso para el skinning. 4 componentes: peso de articulación 1-4 |
ColorSemantic | El atributo es un vector de color de vértice. 4 componentes: r, g, b y a |
TargetPositionSemantic | El atributo es una posición para el primer objetivo de morfo. 3 componentes: x, y y z |
TargetNormalSemantic | El atributo es un vector normal para el primer objetivo de morfo. 3 componentes: x, y y z |
TargetTangentSemantic | El atributo es un vector tangente para el primer objetivo de morfo. 3 componentes: x, y y z |
TargetBinormalSemantic | El atributo es un vector binormal para el primer objetivo de morfo. 3 componentes: x, y y z |
Además, « semantic » puede ser « IndexSemantic ». En este caso, el atributo no representa una entrada en el búfer de vértices, sino que describe los datos de índice en el búfer de índices. Dado que siempre hay un único índice por vértice, « offset » no tiene sentido para el búfer de índices y debe dejarse en cero.
El tipo de componente puede ser uno de los siguientes:
| Constante | Descripción |
|---|---|
U16Type | El tipo de componente de índice es un entero sin signo de 16 bits. Solo se admite para IndexSemantic. |
U32Type | El atributo (o componente de índice) es un entero sin signo de 32 bits. |
I32Type | El atributo es un entero de 32 bits con signo. Ten en cuenta que es posible que las versiones antiguas de OpenGL (como la 2.1 u OpenGL ES 2.0) no admitan este tipo de datos. |
F32Type | El atributo es un número flotante de precisión simple. Nota: Los datosdel índice de la articulación suelen ser de tipo « Nota: Para los datos de índice ( Nota: TargetXXXSemantics quedará obsoleto. Se puede utilizar addTargetAttribute para los objetivos de morfo. Actualmente, estas semánticas solo se admiten por motivos de compatibilidad con versiones anteriores. Si se utilizan de forma mixta con addTargetAttribute y setTargetData, no se puede garantizar el resultado. |
void QQuick3DGeometry::addAttribute(const QQuick3DGeometry::Attribute &attribute)
Añade la descripción de los atributos de los vértices. Cada atributo tiene una «semántica», que especifica el uso del atributo y el número de componentes que tiene; un «desplazamiento» desde el inicio del vértice hasta la ubicación del atributo dentro del mismo; y un «tipo de componente» que especifica el tipo de datos y el tamaño del atributo.
Se trata de una función sobrecargada.
void QQuick3DGeometry::addSubset(int offset, int count, const QVector3D &boundsMin, const QVector3D &boundsMax, const QString &name = {})
Añade un nuevo subconjunto a la geometría. Los subconjuntos permiten renderizar partes de la geometría con materiales diferentes. Los materiales se especifican en model.
Si la geometría tiene un búfer de índices, entonces offset y count son el desplazamiento de la primitiva y el recuento de índices del subconjunto, respectivamente. Si la geometría solo tiene un búfer de vértices, el desplazamiento es el desplazamiento de vértices y el recuento es el número de vértices del subconjunto.
Los límites boundsMin y boundsMax deben abarcar el subconjunto, al igual que los límites de la geometría. Además, el subconjunto puede tener un name.
[since 6.6] void QQuick3DGeometry::addTargetAttribute(quint32 targetId, QQuick3DGeometry::Attribute::Semantic semantic, int offset, int stride = 0)
Añade la descripción del atributo de destino de transformación. Cada atributo tiene un « targetId » al que pertenece, un « semantic » que especifica el uso del atributo y el número de componentes que tiene, un « offset » desde el inicio hasta el vértice y la ubicación del atributo dentro de un vértice, y un « stride », que es el tamaño en bytes entre los elementos.
Nota: El «targetId» debe incrementarse a partir de 0 sin saltarse ningún número, y todos los destinos deben tener los mismos atributos.
Nota: La semántica es la misma que la del atributo de vértice, pero no se permiten IndexSemantic, JointSemantic ni WeightSemantic para los atributos de destino.
Nota: Los «componentTypes» de todos los atributos de destino deben ser de tipo «F32Type».
Nota: Si no se especifica el stride o este es menor o igual que cero, se considera que el atributo está empaquetado de forma compacta.
Esta función se introdujo en Qt 6.6.
Véase también addAttribute.
[since 6.6] void QQuick3DGeometry::addTargetAttribute(const QQuick3DGeometry::TargetAttribute &attribute)
Añade la descripción del atributo de destino de morfo. Cada atributo tiene un «targetId» al que pertenece, una «semántica», que especifica el uso del atributo y el número de componentes que tiene, un «offset» desde el principio hasta el vértice que indica la ubicación del atributo dentro de un vértice, y un «stride», que es el tamaño en bytes entre los elementos.
Se trata de una función sobrecargada.
Esta función se introdujo en Qt 6.6.
QQuick3DGeometry::Attribute QQuick3DGeometry::attribute(int index) const
Devuelve el número de definición del atributo index
Las definiciones de los atributos están numeradas del 0 al attributeCount() - 1
int QQuick3DGeometry::attributeCount() const
Devuelve el número de atributos definidos para esta geometría.
Véase también attribute.
QVector3D QQuick3DGeometry::boundsMax() const
Devuelve la coordenada máxima del volumen delimitador.
Véase también setBounds.
QVector3D QQuick3DGeometry::boundsMin() const
Devuelve la coordenada mínima del volumen delimitador.
Véase también setBounds.
void QQuick3DGeometry::clear()
Restablece la geometría a su estado inicial, borrando los datos de vértices e índices establecidos anteriormente, así como los atributos.
QByteArray QQuick3DGeometry::indexData() const
Devuelve los datos del búfer de índices.
Véase también setIndexData().
QQuick3DGeometry::PrimitiveType QQuick3DGeometry::primitiveType() const
Devuelve el tipo primitivo utilizado al renderizar. El valor por defecto es ` Triangles`.
Véase también setPrimitiveType.
void QQuick3DGeometry::setBounds(const QVector3D &min, const QVector3D &max)
Establece el volumen delimitador de la geometría en el cubo definido por los puntos min y max. Se utiliza para picking.
void QQuick3DGeometry::setIndexData(const QByteArray &data)
Establece el búfer de índice en data. Para utilizar el dibujo indexado, añade un atributo con IndexSemantic
Véase también ` indexData()` y ` addAttribute`.
void QQuick3DGeometry::setIndexData(int offset, const QByteArray &data)
Actualiza un subconjunto del búfer de índice. ` offset ` especifica el desplazamiento en bytes, mientras que ` data ` especifica el tamaño y los datos.
Esta función no cambiará el tamaño del búfer. Si offset + data.size() es mayor que el tamaño actual del búfer, se ignorarán los datos que sobrepasen dicho tamaño.
Nota: Las funciones de actualización parcial para datos de vértices, índices y objetivos de transformación no ofrecen ninguna garantía sobre cómo se implementan dichos cambios internamente. Dependiendo de la implementación subyacente, incluso los cambios parciales pueden dar lugar a la actualización de todo el recurso gráfico.
Esta es una función sobrecargada.
void QQuick3DGeometry::setPrimitiveType(QQuick3DGeometry::PrimitiveType type)
Establece el tipo primitivo utilizado para el renderizado en « type ».
| Constante | Descripción |
|---|---|
Points | Las primitivas son puntos. |
LineStrip | Las primitivas son líneas en una franja. |
Lines | Las primitivas son líneas en una lista. |
TriangleStrip | Las primitivas son triángulos en una franja. |
TriangleFan | Las primitivas son triángulos en abanico. Ten en cuenta que es posible que los triángulos en abanico no sean compatibles en tiempo de ejecución, dependiendo de la API gráfica subyacente. |
Triangles | Las primitivas son triángulos en una lista. |
El valor inicial es Triangles.
Nota: Ten en cuenta que es posible que los abanicos de triángulos (TriangleFan) no sean compatibles en tiempo de ejecución, dependiendo de la API gráfica subyacente. Por ejemplo, con Direct 3D, esta topología no funcionará en absoluto.
Nota: El tamaño de los puntos para «Points» y el grosor de las líneas para «Lines» y «LineStrip» se controlan mediante material. Sin embargo, ten en cuenta que es posible que no se admitan tamaños distintos de 1 en tiempo de ejecución, dependiendo de la API gráfica subyacente.
Véase también primitiveType().
void QQuick3DGeometry::setStride(int stride)
Establece el paso del búfer de vértices en stride, medido en bytes. Se trata de la distancia entre dos vértices consecutivos del búfer.
Por ejemplo, un búfer de vértices entrelazado y compactado para una geometría que utilice PositionSemantic, IndexSemantic y ColorSemantic tendrá un paso de 28 (siete flotantes en total: tres para la posición, cuatro para el color y ninguno para los índices, que no se incluyen en el búfer de vértices).
Nota: QQuick3DGeometry espera, y solo funciona con, datos de vértices con una disposición de atributos intercalada.
Véase también stride() y addAttribute.
[since 6.6] void QQuick3DGeometry::setTargetData(const QByteArray &data)
Establece el búfer del objetivo de transformación data. El búfer debe contener todos los datos del objetivo de transformación.
Esta función se introdujo en Qt 6.6.
Véase también targetData() y addTargetAttribute.
[since 6.6] void QQuick3DGeometry::setTargetData(int offset, const QByteArray &data)
Actualiza un subconjunto del búfer de destino de la transformación. ` offset ` especifica el desplazamiento en bytes, mientras que ` data ` especifica el tamaño y los datos.
Esta función no cambiará el tamaño del búfer. Si offset + data.size() es mayor que el tamaño actual del búfer, los datos que sobrepasen dicho tamaño se ignorarán.
Nota: Las funciones de actualización parcial para datos de vértices, índices y objetivos de transformación no ofrecen ninguna garantía sobre cómo se implementan dichos cambios internamente. Dependiendo de la implementación subyacente, incluso los cambios parciales pueden dar lugar a la actualización de todo el recurso gráfico.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.6.
void QQuick3DGeometry::setVertexData(const QByteArray &data)
Establece el búfer de vértices data. El búfer debe contener todos los datos de vértices empaquetados en la matriz, tal y como se describe en las definiciones de los atributos. Ten en cuenta que esto no incluye los atributos con IndexSemantic, que pertenecen al búfer de índices.
Véase también vertexData(), addAttribute, setStride y setIndexData.
void QQuick3DGeometry::setVertexData(int offset, const QByteArray &data)
Actualiza un subconjunto del búfer de vértices. ` offset ` especifica el desplazamiento en bytes, mientras que ` data ` especifica el tamaño y los datos.
Esta función no cambiará el tamaño del búfer. Si offset + data.size() es mayor que el tamaño actual del búfer, los datos que sobrepasen dicho tamaño se ignorarán.
Nota: Las funciones de actualización parcial para datos de vértices, índices y objetivos de morfo no ofrecen ninguna garantía sobre cómo se implementan dichos cambios internamente. Dependiendo de la implementación subyacente, incluso los cambios parciales pueden dar lugar a la actualización de todo el recurso gráfico.
Esta es una función sobrecargada.
int QQuick3DGeometry::stride() const
Devuelve el paso en bytes del búfer de vértices.
Véase también setStride.
QVector3D QQuick3DGeometry::subsetBoundsMax(int subset) const
Devuelve el número máximo de límites de un objeto ` subset`.
Véase también subsetBoundsMin.
QVector3D QQuick3DGeometry::subsetBoundsMin(int subset) const
Devuelve el número de límites mínimos de un objeto ` subset`.
Véase también subsetBoundsMax.
int QQuick3DGeometry::subsetCount() const
Devuelve el número de subconjuntos.
int QQuick3DGeometry::subsetCount(int subset) const
Devuelve el recuento de primitivas del subconjunto.
Véase también subsetOffset.
QString QQuick3DGeometry::subsetName(int subset) const
Devuelve el nombre « subset ».
int QQuick3DGeometry::subsetOffset(int subset) const
Devuelve el desplazamiento « subset » al búfer de vértices o de índices.
Véase también subsetCount.
[since 6.6] QQuick3DGeometry::TargetAttribute QQuick3DGeometry::targetAttribute(int index) const
Devuelve el número de definición del atributo «morph target» index
Las definiciones de atributos se numeran del 0 al attributeCount() - 1
Esta función se introdujo en Qt 6.6.
[since 6.6] int QQuick3DGeometry::targetAttributeCount() const
Devuelve el número de atributos de destino de transformación definidos para esta geometría.
Esta función se introdujo en Qt 6.6.
Véase también targetAttribute.
[since 6.6] QByteArray QQuick3DGeometry::targetData() const
Devuelve los datos del búfer de destino establecidos mediante ` setTargetData`.
Esta función se introdujo en Qt 6.6.
Véase también ` setTargetData()`.
QByteArray QQuick3DGeometry::vertexData() const
Devuelve el conjunto de datos del búfer de vértices establecido mediante ` setVertexData`.
Véase también setVertexData().
© 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.