Revision control

Copy as Markdown

// Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB).
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qt3drender-geometry.html
\title Qt 3D Render Geometry
\brief Presents the classes provided by the Qt 3D Render aspect to specify
data to the renderer, typically containing geometry.
Qt 3D Render provides a generic way of storing geometry data and specifying
how it should be read by the renderer.
\list
\li \l {Buffer}
\li \l {Attribute}
\li \l {Geometry}
\li \l {GeometryRenderer}
\endlist
\section2 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).
\code
Buffer {
id: vertexBuffer
type: Buffer.VertexBuffer
data: buildVertexBufferData()
}
\endcode
\section2 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.
\code
Attribute {
attributeType: Attribute.VertexAttribute
vertexBaseType: Attribute.Float
vertexSize: 3
byteOffset: 0
byteStride: 9 * 4
count: 4
name: defaultPositionAttributeName()
buffer: vertexBuffer
}
\endcode
\section2 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.
\code
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
}
\endcode
\section2 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.
\code
GeometryView {
instanceCount: 1
indexOffset: 0
firstInstance: 0
primitiveType: GeometryRenderer.Triangles
geometry: Geometry { ... }
}
\endcode
\section2 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.
\code
GeometryRenderer {
view: GeometryView { ... }
}
\endcode
\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.
*/