Класс 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, иерархия сцены гарантирует ожидание выполнения всех задач, отправленных в очередь команд графики сцены, перед удалением узлов сцены. Поэтому нет необходимости вызывать дополнительные ожидания, если реализация 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) координаты вершины, треугольник, покрывающий половину элемента, можно задать как (width - 1, height - 1), (0, 0), (0, height - 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().