Класс QSGRenderNode

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

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

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

Общедоступные типы

Общедоступные функции

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

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

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

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

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

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

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

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

Тип StateFlags — это псевдоним для 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 записывает renderpass, поэтому нет возможности изменить целевой объект и начать другой renderpass (по крайней мере, в этом буфере команд). Поэтому возвращать значение с установленным RenderTargetState нелогично.

Программный бэкенд экспонирует свой 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().