Класс 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 эквивалент:

set_target_properties(application PROPERTIES
    QT_QML_MODULE_VERSION 1.0
    QT_QML_MODULE_URI Example
)
qt6_qml_type_registration(application)

Реализация класса должна добавить 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-координат и описать её в атрибуте TexCoordSemantic. Некоторые материалы могут также потребовать касательных и бинормалей.

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

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);
}

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

Примечание: Ожидается, что данные вершин будут соответствовать соглашениям OpenGL. Это означает, что данные должны быть предоставлены с предположением, что ось Y направлена вверх в системе нормализованных координат устройства, а передние грани имеют против часовой стрелки направление обхода.

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

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

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

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

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

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

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

Примечание: Данные индекса сустава обычно I32Type. F32Type также поддерживается, чтобы обеспечить работу с API, такими как OpenGL ES 2.0, которые не поддерживают целые атрибуты ввода вершин.

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.

Примечание: Обратите внимание, что треугольные веера (TriangleFan) могут не поддерживаться во время выполнения в зависимости от используемого графического API. Например, в Direct3D эта топология вообще не будет функциональной.

Примечание: Размер точки для Точек и толщина линии для Линий и ЛинииПолосы управляются материалом. Однако имейте в виду, что размеры, отличные от 1, могут не поддерживаться во время выполнения в зависимости от используемого графического API.

См. также 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().