From 6fbf9b65dd4ab6c4b4a1ca3ec0ec76280caba436 Mon Sep 17 00:00:00 2001 From: Paul Lemire Date: Tue, 9 Aug 2016 16:41:32 +0200 Subject: Doc: add section about Geometry Change-Id: Ia3967259d0b54ba326b7ae92388bf2a530719f01 Reviewed-by: Sean Harmer --- src/doc/src/qt3d-overview.qdoc | 2 +- src/doc/src/qt3drender-geometry.qdoc | 154 +++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 src/doc/src/qt3drender-geometry.qdoc (limited to 'src/doc/src') diff --git a/src/doc/src/qt3d-overview.qdoc b/src/doc/src/qt3d-overview.qdoc index 7e9c7b4c3..9bbd7f988 100644 --- a/src/doc/src/qt3d-overview.qdoc +++ b/src/doc/src/qt3d-overview.qdoc @@ -62,7 +62,7 @@ \list \li 2D and 3D rendering for C++ and Qt Quick applications - \li Meshes + \li Meshes and \l {Qt 3D Render Geometry}{Geometry} \li \l {Materials} \li \l {Shaders} \li \l {Shadow Mapping}{Shadow mapping} diff --git a/src/doc/src/qt3drender-geometry.qdoc b/src/doc/src/qt3drender-geometry.qdoc new file mode 100644 index 000000000..03e84b1d7 --- /dev/null +++ b/src/doc/src/qt3drender-geometry.qdoc @@ -0,0 +1,154 @@ +/**************************************************************************** +** +** Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB). +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.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 Qt3DRender::QBuffer class stores the raw data. This acts purely as an + array of memory. In most cases a Qt3DRender::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 + + Qt3DRender::QAttribute specifies how data contained in the referenced + buffer should be extracted and passed to an input of a vertex shader. It + references a Qt3DRender::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 Qt3DRender::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 GeometryRenderer + + Qt3DRender::QGeometryRenderer is a QComponent which when aggregated by a + QEntity allows to draw the Qt3DRender::QGeometry it references. It provides + properties to control the draw call such as the number of instances to be + drawn, the starting instance, the type of + Qt3DRender::QGeometryRenderer::PrimitiveType to be used, etc. A + Qt3DRender::QGeometryRenderer is translated into a draw call to the + underlying graphics API. + + \code + GeometryRenderer { + instanceCount: 1 + indexOffset: 0 + firstInstance: 0 + primitiveType: GeometryRenderer.Triangles + geometry: Geometry { ... } + } + \endcode + + */ -- cgit v1.2.3