Qt Quick 3D - Ejemplo de geometría personalizada
Muestra cómo proporcionar datos de vértices personalizados desde C++ y QML.

Este ejemplo utiliza « QQuick3DGeometry » y « the geometry property » de Model para renderizar una malla con coordenadas de vértices, normales y texturas especificadas desde C++ y QML, en lugar de utilizar un recurso predefinido.
Además, también se muestra el uso de ` GridGeometry `. ` GridGeometry ` es una implementación integrada de ` QQuick3DGeometry ` que proporciona una malla con primitivas de línea adecuadas para mostrar una cuadrícula.
En este ejemplo nos centraremos en el código que proporciona la geometría personalizada, así que echemos primero un vistazo al archivo de cabecera de C++ de ` ExampleTriangleGeometry `:
class ExampleTriangleGeometry : public QQuick3DGeometry
{
Q_OBJECT
QML_NAMED_ELEMENT(ExampleTriangleGeometry)
Q_PROPERTY(bool normals READ normals WRITE setNormals NOTIFY normalsChanged)
Q_PROPERTY(float normalXY READ normalXY WRITE setNormalXY NOTIFY normalXYChanged)
Q_PROPERTY(bool uv READ uv WRITE setUV NOTIFY uvChanged)
Q_PROPERTY(float uvAdjust READ uvAdjust WRITE setUVAdjust NOTIFY uvAdjustChanged)
public:
ExampleTriangleGeometry();
bool normals() const { return m_hasNormals; }
void setNormals(bool enable);
float normalXY() const { return m_normalXY; }
void setNormalXY(float xy);
bool uv() const { return m_hasUV; }
void setUV(bool enable);
float uvAdjust() const { return m_uvAdjust; }
void setUVAdjust(float f);
signals:
void normalsChanged();
void normalXYChanged();
void uvChanged();
void uvAdjustChanged();
private:
void updateData();
bool m_hasNormals = false;
float m_normalXY = 0.0f;
bool m_hasUV = false;
float m_uvAdjust = 0.0f;
};Lo más importante que hay que tener en cuenta es que nuestra clase ` ExampleTriangleGeometry ` hereda de ` QQuick3DGeometry ` y que llamamos a la macro ` QML_NAMED_ELEMENT(ExampleTriangleGeometry) `, lo que hace que nuestra clase sea accesible en QML. También hay algunas propiedades definidas mediante la macro ` Q_PROPERTY ` que se exponen automáticamente en nuestro objeto QML. Ahora, veamos el modelo QML:
Model {
id: triangleModel
visible: false
scale: Qt.vector3d(100, 100, 100)
geometry: ExampleTriangleGeometry {
normals: cbNorm.checked
normalXY: sliderNorm.value
uv: cbUV.checked
uvAdjust: sliderUV.value
}
materials: [
PrincipledMaterial {
Texture {
id: baseColorMap
source: "qt_logo_rect.png"
}
cullMode: PrincipledMaterial.NoCulling
baseColorMap: cbTexture.checked ? baseColorMap : null
specularAmount: 0.5
}
]
}Fíjate en que especificamos la propiedad ` geometry ` para utilizar nuestra clase ` ExampleTriangleGeometry `, con las propiedades pertinentes especificadas. Esto es todo lo que se necesita en el lado de QML para utilizar una geometría personalizada.
Ahora, veamos la otra parte importante del código C++, concretamente el método ` updateData() `. Este método crea y carga los datos de nuestra geometría personalizada cada vez que se crea una clase ` ExampleTriangleGeometry ` o se actualiza cualquiera de sus propiedades QML.
void ExampleTriangleGeometry::updateData()
{
clear();
int stride = 3 * sizeof(float);
if (m_hasNormals)
stride += 3 * sizeof(float);
if (m_hasUV)
stride += 2 * sizeof(float);
QByteArray vertexData(3 * stride, Qt::Initialization::Uninitialized);
float *p = reinterpret_cast<float *>(vertexData.data());
// a triangle, front face = counter-clockwise
*p++ = -1.0f; *p++ = -1.0f; *p++ = 0.0f;
if (m_hasNormals) {
*p++ = m_normalXY; *p++ = m_normalXY; *p++ = 1.0f;
}
if (m_hasUV) {
*p++ = 0.0f + m_uvAdjust; *p++ = 0.0f + m_uvAdjust;
}
*p++ = 1.0f; *p++ = -1.0f; *p++ = 0.0f;
if (m_hasNormals) {
*p++ = m_normalXY; *p++ = m_normalXY; *p++ = 1.0f;
}
if (m_hasUV) {
*p++ = 1.0f - m_uvAdjust; *p++ = 0.0f + m_uvAdjust;
}
*p++ = 0.0f; *p++ = 1.0f; *p++ = 0.0f;
if (m_hasNormals) {
*p++ = m_normalXY; *p++ = m_normalXY; *p++ = 1.0f;
}
if (m_hasUV) {
*p++ = 1.0f - m_uvAdjust; *p++ = 1.0f - m_uvAdjust;
}
setVertexData(vertexData);
setStride(stride);
setBounds(QVector3D(-1.0f, -1.0f, 0.0f), QVector3D(+1.0f, +1.0f, 0.0f));
setPrimitiveType(QQuick3DGeometry::PrimitiveType::Triangles);
addAttribute(QQuick3DGeometry::Attribute::PositionSemantic,
0,
QQuick3DGeometry::Attribute::F32Type);
if (m_hasNormals) {
addAttribute(QQuick3DGeometry::Attribute::NormalSemantic,
3 * sizeof(float),
QQuick3DGeometry::Attribute::F32Type);
}
if (m_hasUV) {
addAttribute(QQuick3DGeometry::Attribute::TexCoordSemantic,
m_hasNormals ? 6 * sizeof(float) : 3 * sizeof(float),
QQuick3DGeometry::Attribute::F32Type);
}
}El método comienza llamando a clear() para borrar todos los datos cargados anteriormente. A continuación, calcula el paso (stride) de los vértices, teniendo en cuenta la presencia de normales y coordenadas UV. A continuación, se crea una matriz de bytes para almacenar el búfer de vértices, que luego se rellena con los vértices de un único triángulo con vértices en (-1, -1, 0), (1, -1, 0) y (0, 1, 0).
A continuación, se cargan los datos de los vértices y se establece el stride llamando a ` setVertexData() ` y ` setStride()`. Los límites de la geometría se establecen llamando a ` setBounds`. Aunque no se utiliza en este ejemplo, establecer los límites es necesario para que funcionen las sombras. A continuación, se establece el tipo de primitiva llamando a setPrimitiveType(). Por último, especificamos cómo se distribuyen en memoria los atributos de posición, normal y coordenadas UV en el búfer cargado anteriormente, llamando a addAttribute() para cada atributo.
© 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.