Класс QSGRenderNode

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

Этот класс был введён в Qt 5.8.

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

Типы публичного интерфейса

Публичные функции

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

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

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

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

Тип RenderingFlags — это typedef для QFlags<RenderingFlag>. Он хранит логическое ИЛИ сочетание значений RenderingFlag.

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

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

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

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

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

[override virtual] QSGRenderNode::~QSGRenderNode()

Деструктор узла отрисовки. Производные классы должны выполнять очистку, аналогично releaseResources(), в этом методе.

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

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

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

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

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

С API, отличными от OpenGL, единственными релевантными значениями являются те, которые соответствуют динамическим изменениям состояния, записанным в списке/буфере команд. Например, RSSetViewports, RSSetScissorRects, OMSetBlendFactor, OMSetStencilRef в случае D3D12 или vkCmdSetViewport, vkCmdSetScissor, vkCmdSetBlendConstants, vkCmdSetStencilRef в случае Vulkan, и только когда такие команды были добавлены в список команд графа сцены, запрошенный через ресурс QSGRendererInterface::CommandList. Состояния, заданные в объектах состояния конвейера, не нуждаются в отчётности здесь. Аналогично, параметры, связанные с вызовами отрисовки (состояния конвейера, наборы дескрипторов, привязки буферов вершин или индексов, сигнатура корня, кучи дескрипторов и т.д.), всегда устанавливаются заново графом сцены, поэтому render() может свободно их менять.

Примечание: RenderTargetState больше не поддерживается API, такими как Vulkan. Это по своей природе. render() вызывается, когда граф сцены Qt Quick записывает проход отрисовки, поэтому нет возможности изменить цель и начать другой проход отрисовки (по крайней мере, в данном буфере команд).

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

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

Реализация по умолчанию возвращает 0, что означает, что в 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 предоставляется как средство реализации пользовательских 2D- или 2.5D-элементов Qt Quick. Он не предназначен для интеграции истинного 3D-контента в сцену Qt Quick. Этот случай лучше поддерживается QQuickFramebufferObject, QQuickWindow::beforeRendering() или их эквивалентами для API, отличных от OpenGL.

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

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

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

В случае устаревшего, прямого OpenGL-рендерера следующие состояния устанавливаются в контексте потока рендеринга до вызова этой функции:

• glColorMask(true, true, true, true)
• glDepthMask(false)
• glDisable(GL_DEPTH_TEST)
• glStencilFunc(GL_EQUAL, state.stencilValue, 0xff); glStencilOp(GL_KEEP, GL_KEEP, GL_KEEP) в зависимости от обрезки
• 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, могут иметь произвольные значения.

Примечание: При использовании других графических API состояния не устанавливаются, поскольку многие из них не имеют понятия о традиционной машине состояний OpenGL. Вместо этого от реализации ожидается создание объектов состояния конвейера с включенными необходимыми смешиванием, отсечением и проверкой маскирования. Обратите внимание, что это также включает OpenGL через RHI. Новым реализациям QSGRenderNode рекомендуется явно устанавливать все состояния отсечения, маскирования и смешивания (как показано в списке выше), даже если они ориентированы на OpenGL.

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

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

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

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

В некоторых графических API может потребоваться также подключение к сигналу QQuickWindow::beforeRendering(), поскольку он испускается до записи начала прохода рендеринга в буфер команд (vkCmdBeginRenderPass с Vulkan или начало кодирования через MTLRenderCommandEncoder в случае Metal). Операции копирования не могут выполняться внутри render() с такими API. Вместо этого сделайте это в слоте, подключенном (с помощью DirectConnection) к сигналу beforeRendering.

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