Класс QSGRenderNode

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

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

Типы публичного доступа

Функции публичного доступа

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

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

Перечисление 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, OMSetBlendState, OMSetDepthStencilState в случае D3D11 или vkCmdSetViewport, vkCmdSetScissor, vkCmdSetBlendConstants, vkCmdSetStencilRef в случае Vulkan, и только когда такие команды были добавлены в список команд сцены, запрошенный через ресурс QSGRendererInterface::CommandList. Состояния, установленные в объектах состояния конвейера, не требуется сообщать здесь. Аналогичным образом, настройки, связанные с вызовами отрисовки (состояния конвейера, наборы дескрипторов, привязки буферов вершин или индексов, сигнатура корня, кучи дескрипторов и т. д.), всегда устанавливаются снова иерархией сцен, поэтому render() может свободно их изменять.

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

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

Реализация по умолчанию возвращает 0, означая, что в 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, since 6.0] void QSGRenderNode::prepare()

Вызывается на стадии подготовки кадра. Перед каждым вызовом render() есть вызов этой функции.

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

Реализация по умолчанию пуста.

Эта функция была введена в Qt 6.0.

[virtual] QRectF QSGRenderNode::rect() const

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

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

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

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

[virtual] void QSGRenderNode::releaseResources()

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

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

В отличие от деструктора, ожидается, что 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) по часовой стрелке.

Информация об обрезке рассчитывается до вызова функции. Реализации, желающие учитывать обрезку, могут установить обрезку или маскирование на основе информации в 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, могут иметь произвольные значения.

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

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

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

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

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