diff options
Diffstat (limited to 'src/core/doc/src/qt3drender-geometry.qdoc')
| -rw-r--r-- | src/core/doc/src/qt3drender-geometry.qdoc | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/src/core/doc/src/qt3drender-geometry.qdoc b/src/core/doc/src/qt3drender-geometry.qdoc new file mode 100644 index 000000000..478400469 --- /dev/null +++ b/src/core/doc/src/qt3drender-geometry.qdoc @@ -0,0 +1,160 @@ +/**************************************************************************** +** +** Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB). +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \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. + + */ |