Класс QSGRenderNode

Класс QSGRenderNode представляет набор пользовательских команд отрисовки, нацеленных на графический API, используемый в дереве сцены. Подробнее...

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

Открытые типы

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

• 20 открытых функций, унаследованных от QSGNode

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

Класс QSGRenderNode представляет набор пользовательских команд отрисовки, нацеленных на графический API, используемый в дереве сцены.

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

перечисление QSGRenderNode::RenderingFlagфлаги QSGRenderNode::RenderingFlags

Возможные значения для битовой маски, возвращаемой функцией flags().

Тип RenderingFlags является псевдонимом для QFlags<RenderingFlag>. Он хранит логическое ИЛИ комбинацию значений RenderingFlag.

См. также render() и rect().

перечисление QSGRenderNode::StateFlagфлаги QSGRenderNode::StateFlags

Это перечисление — битовая маска, идентифицирующая несколько состояний.

Тип StateFlags — псевдоним для QFlags<StateFlag>. Он хранит логическое ИЛИ комбинацию значений StateFlag.

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

QSGRenderNode::QSGRenderNode()

Конструктор по умолчанию для экземпляра QSGRenderNode.

[override virtual] QSGRenderNode::~QSGRenderNode()

Уничтожает узел отрисовки. От производных классов ожидается выполнение очистки, аналогичной releaseResources() здесь.

При использовании низкоуровневого графического API дерево сцены обеспечит ожидание CPU, пока GPU завершит всю работу, отправленную в очередь команд графики дерева сцены, прежде чем узлы дерева сцены будут удалены. Поэтому нет необходимости издавать дополнительные ожидания здесь, если только реализация render() не использует дополнительные очереди команд.

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

[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const

Эта функция должна возвращать маску, где каждый бит представляет изменённое состояние графики функцией render():

• DepthState — маска записи глубины, включённый тест глубины, функция сравнения глубины
• StencilState — маски записи штампа, включённый тест штампа, операции штампа, функции сравнения штампа
• ScissorState — включение ножниц, включённый тест ножниц
• ColorState — цвет очистки, маска записи цвета
• BlendState — включение смешивания, функция смешивания
• CullState — лицевая грань, включённая обрезка грани
• ViewportState — область просмотра
• RenderTargetState — мишень для отрисовки

Функция вызывается рендерером, чтобы он мог сбросить состояния после отрисовки этого узла. Это упрощает реализацию render(), так как она не должна запрашивать и восстанавливать эти состояния.

Реализация по умолчанию возвращает 0, что означает, что в render() не было изменено никакого значимого состояния.

При использовании API, отличных от OpenGL, соответствующие состояния устанавливаются только через список команд (например, OMSetRenderTargets, RSSetViewports, RSSetScissorRects, OMSetBlendFactor, OMSetStencilRef в случае D3D12) и только тогда, когда такие команды были добавлены в список команд сцены, запрошенный через ресурс QSGRendererInterface::CommandList. Состояния, установленные в объектах состояния конвейера, здесь сообщать не нужно. Аналогично, параметры, связанные с вызовами отрисовки (подписи корневых ресурсов, кучи дескрипторов и т. д.), всегда устанавливаются снова графическим ядром, чтобы render() мог свободно их менять.

Бэкенд программного обеспечения предоставляет QPainter и сохраняет и восстанавливает состояния перед и после вызова render(). Поэтому сообщать о любых изменённых состояниях отсюда не требуется.

Примечание: Эта функция может быть вызвана до render().

const QSGClipNode *QSGRenderNode::clipList() const

Возвращает текущий список обрезки.

[virtual] QSGRenderNode::RenderingFlags QSGRenderNode::flags() const

Возвращает флаги, описывающие поведение этого узла отрисовки.

Реализация по умолчанию возвращает 0.

См. также RenderingFlag и rect().

qreal QSGRenderNode::inheritedOpacity() const

Возвращает текущую эффективную непрозрачность.

const QMatrix4x4 *QSGRenderNode::matrix() const

Возвращает указатель на текущую матрицу модели-представления.

[virtual] QRectF QSGRenderNode::rect() const

Возвращает прямоугольник ограничивающей рамки в координатах элемента для области, с которой render() взаимодействует. Значение используется только тогда, когда flags() включает BoundedRectRendering, в противном случае игнорируется.

Сообщения прямоугольника в сочетании с BoundedRectRendering особенно важны с software бэкэндом, поскольку в противном случае наличие узла отрисовки в сцене вызовет обновление всего экрана, пропуская все оптимизации частичных обновлений.

Для узлов отрисовки, покрывающих всю область соответствующего QQuickItem, значением будет (0, 0, item->width(), item->height()).

Примечание: Узлы также могут отрисовывать за пределами границ, заданных шириной и высотой элемента, так как узлы графического ядра не ограничены геометрией QQuickItem, при условии, что это корректно сообщается этой функцией.

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

[virtual] void QSGRenderNode::releaseResources()

Эта функция вызывается, когда все пользовательские графические ресурсы, выделенные этим узлом, должны быть немедленно освобождены. В случае, если узел не выделяет графические ресурсы (буферы, текстуры, целевые области отрисовки, ограждения и т. д.) напрямую через используемый графический API, здесь ничего делать не нужно.

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

Примечание: Некоторые бэкэнды графического ядра могут выбрать не вызывать эту функцию. Поэтому ожидается, что реализации QSGRenderNode выполняют очистку как в деструкторе, так и в releaseResources().

В отличие от деструктора, ожидается, что render() может повторно инициализировать все необходимые ресурсы, когда вызывается после вызова releaseResources().

С OpenGL контекст OpenGL графического ядра сцены будет текущим как при вызове деструктора, так и при вызове этой функции.

[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)

Эта функция вызывается рендерером и должна отрисовать этот узел, напрямую вызывая команды в используемом в данный момент графическом API (OpenGL, Direct3D и т. д.).

Эффективную непрозрачность можно получить с помощью inheritedOpacity().

Матрица проекции доступна через state, а матрицу модели-представления можно получить с помощью matrix(). Объединённая матрица — это матрица проекции, умноженная на матрицу модели-представления. Правильное расположение элементов в сцене обеспечивается матрицей проекции.

При использовании предоставленных матриц система координат для данных вершин соответствует обычным соглашениям QQuickItem: верхний левый угол — (0, 0), нижний правый — ширина() и высота() соответствующего QQuickItem минус один. Например, предполагая макет из двух чисел с плавающей точкой (x-y) на вершину, треугольник, покрывающий половину элемента, можно указать как (ширина - 1, высота - 1), (0, 0), (0, высота - 1) по направлению против часовой стрелки.

Примечание: QSGRenderNode предоставляется как средство реализации пользовательских элементов Qt Quick 2D или 2.5D. Он не предназначен для интеграции истинно 3D-контента в сцену Qt Quick. Для этого случая лучше подойдут QQuickFramebufferObject, QQuickWindow::beforeRendering() или их аналоги для API, отличных от OpenGL.

Информация об обрезке вычисляется перед вызовом функции, но не активируется. Реализации, желающие учесть обрезку, могут настроить сдвиг или маскирование стереоскопического эффекта на основе информации в state. Некоторые бэкэнды графического ядра, в частности программные, не используют сдвиг или маскирование стереоскопического эффекта. В этом случае область обрезки предоставляется как обычный QRegion.

Для OpenGL следующие состояния устанавливаются в контексте потока отрисовки перед вызовом этой функции:

• glDepthMask(false)
• glDisable(GL_DEPTH_TEST)
• glStencilFunc(GL_EQUAL, state.stencilValue, 0xff) в зависимости от обрезки
• glScissor(state.scissorRect.x(), state.scissorRect.y(), state.scissorRect.width(), state.scissorRect.height()) в зависимости от обрезки
• glEnable(GL_BLEND)
• glBlendFunc(GL_ONE, GL_ONE_MINUS_SRC_ALPHA)
• glDisable(GL_CULL_FACE)

Состояния, не перечисленные выше, но включённые в StateFlags, могут иметь произвольные значения.

changedStates() должен возвращать, какие состояния меняет эта функция. Если состояние не охвачено StateFlags, состояние должно быть установлено в значение по умолчанию в соответствии со спецификацией OpenGL. Для других API см. документацию для changedStates() для получения дополнительной информации.

Примечание: Запись в буфер глубины отключена при вызове этой функции (например, glDepthMask(false) в случае OpenGL). Включение записи в буфер глубины может привести к неожиданным результатам в зависимости от используемого бэкэнда графического ядра, поэтому узлы должны этого избегать.

Для API, отличных от OpenGL, вероятно, потребуется запросить определённые ресурсы, специфичные для API (например, графическое устройство или список команд/буфер для добавления команд). Это делается через QSGRendererInterface.

См. также QSGRendererInterface и QQuickWindow::rendererInterface().