// 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.

 */
