Qt 3D Render Geometry

Qt 3D Render provides a generic way of storing geometry data and specifying how it should be read by the renderer.

Buffer

The Qt3DCore::QBuffer class stores the raw data. This acts purely as an array of memory. In most cases a Qt3DCore::QBuffer will be used indirectly by being referenced by one or more Qt3DRender::QAttributes. However there are times when a QBuffer may be used directly as the value property of a QParameter when dealing with Uniform Buffer Objects (UBO) or Shader Storage Buffer Objects (SSBO).

Buffer {
    id: vertexBuffer
    type: Buffer.VertexBuffer
    data: buildVertexBufferData()
}

Attribute

Qt3DCore::QAttribute specifies how data contained in the referenced buffer should be extracted and passed to an input of a vertex shader. It references a Qt3DCore::QBuffer and can specify the layout of the attributes by definining the vertex size, the data type, the stride between two vertices and a starting offset. The type of the attribute will also define whether it is to be used as a vertex buffer or as an index buffer. This allows you complete flexibility of how you structure your data in buffers. It is possible to use separate buffers for each vertex attribute, an interleaved buffer containing data for all attributes or a combination of separate and interleaved buffers.

Attribute {
    attributeType: Attribute.VertexAttribute
    vertexBaseType: Attribute.Float
    vertexSize: 3
    byteOffset: 0
    byteStride: 9 * 4
    count: 4
    name: defaultPositionAttributeName()
    buffer: vertexBuffer
}

Geometry

A Qt3DCore::QGeometry aggregates various attributes to form a piece of geometry. Usually a proper geometry will provide an attribute for vertex positions, an attribute for vertex normals and an attribute for texture coordinates. If you want your geometry to also work with normal mapped materials it will need to provide a consistent set of vertex tangent vectors too.

Geometry {
    Attribute {
        attributeType: Attribute.VertexAttribute
        vertexBaseType: Attribute.Float
        vertexSize: 3
        byteOffset: 0
        byteStride: 9 * 4
        count: 4
        name: defaultPositionAttributeName()
        buffer: vertexBuffer
    }

    Attribute {
        attributeType: Attribute.VertexAttribute
        vertexBaseType: Attribute.Float
        vertexSize: 3
        byteOffset: 3 * 4
        byteStride: 9 * 4
        count: 4
        name: defaultNormalAttributeName()
        buffer: vertexBuffer
}

GeometryView

A Qt3DCore::QGeometryView takes a Qt3DCore::QGeometry. It provides properties to control the draw call such as the number of instances to be drawn, the starting instance, the type of Qt3DCore::QGeometryView::PrimitiveType to be used, etc.

It completely defines the details of a mesh so that operations such as bounding volume computation and picking can be done on a mesh without requiring it to be rendered.

GeometryView {
    instanceCount: 1
    indexOffset: 0
    firstInstance: 0
    primitiveType: GeometryRenderer.Triangles
    geometry: Geometry { ... }
}

GeometryRenderer

Qt3DRender::QGeometryRenderer is a QComponent which when aggregated by a QEntity allows to draw the Qt3DCore::QGeometryView it references. A Qt3DRender::QGeometryRenderer is translated into a draw call to the underlying graphics API.

GeometryRenderer {
    view: GeometryView { ... }
}

Note: Prior to Qt 6, Qt3DRender::QGeometryRenderer included details that are now intended to be provided by the view instance. The properties are still there in Qt 6 but will be deprecated and then removed in Qt 7.

© 2024 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.