Класс 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 должна быть предоставлена и описана в атрибуте 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);
}

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

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

См. также Model и Geometry.

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

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

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

Semantic может быть одним из следующих:

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

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

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

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

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

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

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. Например, в Direct 3D эта топология вообще не будет функциональной.

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

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

void QQuick3DGeometry::setStride(int stride)

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

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

Примечание: QQuick3DGeometry ожидает и работает только с данными вершин с интерлизованной структурой атрибутов.

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