Класс 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

Эта функция должна возвращать маску, где каждый бит представляет изменённые графические состояния функцией 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 предоставляется как средство для реализации пользовательских 2D или 2.5D элементов Qt Quick. Он не предназначен для интеграции истинно 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().