Класс QQuick3DGeometry

Базовый класс для определения пользовательской геометрии. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Подробное описание

Класс QQuick3DGeometry может использоваться для задания пользовательской геометрии для модели в сцене Qt Quick 3D.

Хотя это не строго необходимо, типичным использованием является наследование от этого класса. Затем подкласс экспонируется в QML путём регистрации в системе типов. Свойство geometry модели может затем быть установлено для ссылки на экземпляр зарегистрированного типа.

Высокоуровневая структура такого класса обычно похожа на следующее:

class CustomGeometry : public QQuick3DGeometry
{
public:
    CustomGeometry() { rebuildGeometry(); }

    void setSomething() {
       // Change relevant internal data.
       // ...

       // Then rebuild the vertex and index data and pass it to QQuick3DGeometry.
       rebuildGeometry();

       // Finally, trigger an update. This is relevant in case nothing else
       // is changing in the scene; this way we make sure a new frame will
       // be rendered.
       update();
    }

private:
    void rebuildGeometry()
    {
        QByteArray vertices;
        QByteArray indices;
        ...
        setPrimitiveType(Lines);
        setVertexBuffer(vertices);
        setIndexBuffer(indices);
        setStride(3 * sizeof(float)); // e.g. when having 3 components per vertex
        setBounds(...); // minimum and maximum extents, for picking
        addAttribute(PositionSemantic, 0, F32Type);
        ...
    }
};

Этот класс затем может быть зарегистрирован как тип QML и использован с Model.

В Qt 5 регистрация типов происходила с помощью qmlRegisterType:

qmlRegisterType<CustomGeometry>("Example", 1, 0, "CustomGeometry");

В Qt 6 предпочтительный подход — автоматическая регистрация с помощью системы сборки. Вместо вызова qmlRegisterType, файл .pro теперь может содержать:

CONFIG += qmltypes
QML_IMPORT_NAME = Example
QML_IMPORT_MAJOR_VERSION = 1

С CMake автоматическая регистрация является по умолчанию, поэтому нет необходимости в дополнительных настройках помимо базовой настройки модуля QML:

qt_add_qml_module(application
    URI Example
    VERSION 1.0
)

Реализация класса должна добавить QML_NAMED_ELEMENT:

class CustomGeometry : public QQuick3DGeometry
{
    Q_OBJECT
    QML_NAMED_ELEMENT(CustomGeometry)
    ...
};

Код QML может затем использовать пользовательский тип:

import Example 1.0

Model {
    id: customModel
    geometry: CustomGeometry {
    }
}

По меньшей мере, у пользовательской геометрии должны быть указаны следующие:

• данные вершин,
• шаг вершин,
• тип примитива,
• атрибут с PositionSemantic.

Эти данные достаточны для рендеринга сетки. Для индексированного рендеринга должны быть указаны также данные буфера индексов и атрибут с IndexSemantic. Для поддержки выбора (ввода) класс должен указать объём ограничивающей области с помощью setBounds(). Для корректного освещения необходим атрибут с NormalSemantic. При использовании текстурирования материалом необходимо предоставить по крайней мере одну пару координат текстурных Uv и описать её в атрибуте TexCoord0Semantic или TexCoord1Semantic. Некоторые материалы могут также потребовать касательных и бинормалей.

Как конкретный минимальный пример, следующий класс предоставит геометрию для одного треугольника:

class ExampleGeometry : public QQuick3DGeometry
{
    Q_OBJECT
    QML_NAMED_ELEMENT(ExampleGeometry)

public:
    ExampleGeometry();

private:
    void updateData();
};

ExampleGeometry::ExampleGeometry()
{
    updateData();
}

void ExampleGeometry::updateData()
{
    QByteArray v;
    v.resize(3 * 3 * sizeof(float));
    float *p = reinterpret_cast<float *>(v.data());

    // a triangle, front face = counter-clockwise
    *p++ = -1.0f; *p++ = -1.0f; *p++ = 0.0f;
    *p++ = 1.0f; *p++ = -1.0f; *p++ = 0.0f;
    *p++ = 0.0f; *p++ = 1.0f; *p++ = 0.0f;

    setVertexData(v);
    setStride(3 * sizeof(float));

    setPrimitiveType(QQuick3DGeometry::PrimitiveType::Triangles);

    addAttribute(QQuick3DGeometry::Attribute::PositionSemantic,
                 0,
                 QQuick3DGeometry::Attribute::F32Type);
}

В зависимости от освещения в сцене, результат ссылки на эту геометрию из модели:

См. также Model и Геометрия.

Документация по функциям-членам

void QQuick3DGeometry::addAttribute(Attribute::Semantic semantic, int offset, Attribute::ComponentType componentType)

Добавляет описание атрибута вершины. Каждый атрибут имеет semantic, который определяет использование атрибута и количество составляющих, offset от начала вершины до расположения атрибута внутри вершины и componentType, указывающий тип и размер атрибута.

Семантика может быть следующей:

Кроме того, semantic может быть IndexSemantic. В этом случае атрибут не представляет запись в буфере вершин, а описывает данные индекса в буфере индексов. Поскольку всегда существует только один индекс на вершину, offset не имеет смысла для буфера индексов и должен быть оставлен равным нулю.

Тип составляющей может быть одним из следующих:

void QQuick3DGeometry::addAttribute(const QQuick3DGeometry::Attribute &attribute)

Это перегруженный метод.

Добавляет описание атрибута вершины. Каждый атрибут имеет семантику, которая определяет использование атрибута и количество его компонентов, смещение от начала вершины до расположения атрибута внутри вершины, и компонентный тип, определяющий тип и размер атрибута.

QQuick3DGeometry::Attribute QQuick3DGeometry::attribute(int index) const

Возвращает определение атрибута с номером index

Определения атрибутов пронумерованы от 0 до attributeCount() - 1

int QQuick3DGeometry::attributeCount() const

Возвращает количество атрибутов, определённых для этой геометрии.

См. также attribute.

QVector3D QQuick3DGeometry::boundsMax() const

Возвращает максимальную координату ограничивающего объёма.

См. также setBounds.

QVector3D QQuick3DGeometry::boundsMin() const

Возвращает минимальную координату ограничивающего объёма.

См. также setBounds.

void QQuick3DGeometry::clear()

Сбрасывает геометрию в исходное состояние, очищая ранее установленные данные вершин и индексов, а также атрибуты.

QByteArray QQuick3DGeometry::indexData() const

Возвращает данные буфера индексов.

См. также setIndexData().

QQuick3DGeometry::PrimitiveType QQuick3DGeometry::primitiveType() const

Возвращает тип примитива, используемый при отрисовке. Значение по умолчанию — Triangles.

См. также setPrimitiveType.

void QQuick3DGeometry::setBounds(const QVector3D &min, const QVector3D &max)

Устанавливает ограничивающий объём геометрии в куб, определяемый точками min и max. Используется для выбора.

void QQuick3DGeometry::setIndexData(const QByteArray &data)

Устанавливает буфер индексов в data. Для использования индексированной отрисовки добавьте атрибут с IndexSemantic

См. также indexData() и addAttribute.

void QQuick3DGeometry::setIndexData(int offset, const QByteArray &data)

Это перегруженный метод.

Обновляет подмножество буфера индексов. offset указывает смещение в байтах, data — размер и данные.

Эта функция не изменяет размер буфера. Если offset + data.size() больше текущего размера буфера, избыточные данные будут проигнорированы.

void QQuick3DGeometry::setPrimitiveType(QQuick3DGeometry::PrimitiveType type)

Устанавливает тип примитива для отрисовки в type.

Начальное значение — Triangles.

См. также primitiveType().

void QQuick3DGeometry::setStride(int stride)

Устанавливает шаг буфера вершин в stride, измеряемый в байтах. Это расстояние между двумя последовательными вершинами в буфере.

Например, плотно упакованный, перемешанный буфер вершин для геометрии, использующей PositionSemantic, IndexSemantic, и ColorSemantic, будет иметь шаг 28 (Всего семь чисел с плавающей точкой: три для позиции, четыре для цвета и ни одного для индексов, которые не попадают в буфер вершин.)

См. также stride() и addAttribute.

void QQuick3DGeometry::setVertexData(const QByteArray &data)

Устанавливает буфер вершин data. Буфер должен содержать все данные вершин, упакованные в массив, как описано в определениях атрибутов. Обратите внимание, что это не включает атрибуты с IndexSemantic, которые принадлежат буферу индексов.

См. также vertexData(), addAttribute, setStride и setIndexData.

void QQuick3DGeometry::setVertexData(int offset, const QByteArray &data)

Это перегруженный метод.

Обновляет подмножество буфера вершин. offset указывает смещение в байтах, data — размер и данные.

Эта функция не изменяет размер буфера. Если offset + data.size() больше текущего размера буфера, избыточные данные будут проигнорированы.

int QQuick3DGeometry::stride() const

Возвращает шаг в байтах буфера вершин.

См. также setStride.

QByteArray QQuick3DGeometry::vertexData() const

Возвращает данные буфера вершин, установленные с помощью setVertexData.

См. также setVertexData().