Класс QSGMaterialShader

Класс QSGMaterialShader представляет собой программу шейдеров, независимую от графического API. Подробнее...

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

Типы Public

Функции Public

Защищённые функции

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

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

Примечание: Все классы с префиксом QSG должны использоваться только в потоке отрисовки графа сцены. См. Граф сцены и отрисовка для получения дополнительной информации.

Классы QSGMaterial и QSGMaterialShader образуют тесную взаимосвязь. Для одного графа сцены (включая вложенные графы) существует один уникальный экземпляр QSGMaterialShader, который инкапсулирует шейдеры и другие данные, используемые графом сцены для отрисовки объекта с этим материалом. Каждый QSGGeometryNode может иметь уникальный QSGMaterial, который определяет, как должна быть настроена графическая конвейерная обработка при отрисовке узла. Экземпляр QSGMaterialShader никогда не создается пользователем явно, он будет создан по запросу графом сцены через QSGMaterial::createShader(). Граф сцены создаёт экземпляр QSGMaterialShader, вызывая метод QSGMaterial::createShader(), гарантируя, что существует только один экземпляр каждого реализующего шейдеры.

В Qt 5 QSGMaterialShader был связан с OpenGL. Он был построен непосредственно на QOpenGLShaderProgram и имел функции, такие как updateState(), которые могли издавать произвольные команды OpenGL. Это больше не так в Qt 6. QSGMaterialShader не является строго ориентированным на данные, а значит, предоставляет данные (шейдеры и желаемые изменения состояния конвейерной обработки) вместе с логикой, которая обновляет данные в унифицированном буфере. Доступ к графическому API не предоставляется. Это означает, что QSGMaterialShader не может выполнять вызовы OpenGL, Vulkan, Metal или Direct 3D самостоятельно. Вместе с унифицированным управлением шейдерами это позволяет QSGMaterialShader быть написанным один раз и функциональным с любой из поддерживаемых графических API во время выполнения.

Шейдеры, установленные вызовом защищённой функции setShaderFileName(), управляют тем, что материал делает с вершинными данными из геометрии и как обрабатываются фрагменты. QSGMaterialShader обычно устанавливает вершинный и фрагментный шейдеры во время построения. Изменение шейдеров после этого может не привести к желаемому результату и должно быть избегаемо.

В Qt 6, стандартный подход — поставлять .qsb файлы с приложением, обычно встроенные через систему ресурсов и используемые при вызове setShaderFileName(). Файлы .qsb генерируются автономно или по крайней мере на этапе сборки приложения из исходного кода GLSL в стиле Vulkan, используя инструмент qsb из модуля Qt Shader Tools.

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

updateUniformData() — функция, которая чаще всего переопределяется в подклассах. Эта функция должна обновить содержимое QByteArray, которое затем будет предоставлено шейдерам как унифицированный буфер. Любой QSGMaterialShader, у которого есть блок унифицированных переменных в вершинном или фрагментном шейдере, должен переопределить updateUniformData().

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

Изменения состояния конвейера шейдера используются реже. Один из вариантов использования — материалы, которые хотят использовать определённый режим смешивания. Соответствующая функция — updateGraphicsPipelineState(). Эта функция не вызывается, если QSGMaterialShader не включил её, установив флаг UpdatesGraphicsPipelineState. Задача функции — обновить экземпляр структуры GraphicsPipelineState, переданный ей, с желаемыми изменениями. В настоящее время доступны только функции смешивания и обрезки, другие состояния нельзя контролировать с помощью материалов.

Минимальный пример, включающий поддержку текстур, может быть следующим. Здесь мы предполагаем, что Material — это QSGMaterial, который создаёт экземпляр Shader в своём createShader() и хранит QSGTexture, которую мы хотим использовать для сэмплирования в фрагментном шейдере. Вершинный шейдер зависит только от матрицы модели-представления-проекции.

class Shader : public QSGMaterialShader
{
public:
    Shader()
    {
        setShaderFileName(VertexStage, QLatin1String(":/materialshader.vert.qsb"));
        setShaderFileName(FragmentStage, QLatin1String(":/materialshader.frag.qsb"));
    }

    bool updateUniformData(RenderState &state, QSGMaterial *, QSGMaterial *)
    {
        bool changed = false;
        QByteArray *buf = state.uniformData();
        if (state.isMatrixDirty()) {
            const QMatrix4x4 m = state.combinedMatrix();
            memcpy(buf->data(), m.constData(), 64);
            changed = true;
        }
        return changed;
    }

    void updateSampledImage(RenderState &, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *)
    {
        Material *mat = static_cast<Material *>(newMaterial);
        if (binding == 1)
            *texture = mat->texture();
    }
};

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

#version 440
layout(location = 0) in vec4 aVertex;
layout(location = 1) in vec2 aTexCoord;
layout(location = 0) out vec2 vTexCoord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
} ubuf;
out gl_PerVertex { vec4 gl_Position; };
void main() {
    gl_Position = ubuf.qt_Matrix * aVertex;
    vTexCoord = aTexCoord;
}

#version 440
layout(location = 0) in vec2 vTexCoord;
layout(location = 0) out vec4 fragColor;
layout(binding = 1) uniform sampler2D srcTex;
void main() {
    vec4 c = texture(srcTex, vTexCoord);
    fragColor = vec4(c.rgb * 0.5, 1.0);
}

Примечание: Все классы с префиксом QSG должны использоваться только в потоке отрисовки графа сцены. См. Граф сцены и отрисовка для получения дополнительной информации.

См. также QSGMaterial, Граф сцены — настраиваемый материал, Граф сцены — два поставщика текстур и Граф сцены — граф.

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

enum QSGMaterialShader::Flagflags QSGMaterialShader::Flags

Значения флагов, указывающие специальные свойства материала.

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

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

QSGMaterialShader::QSGMaterialShader()

Создаёт новый QSGMaterialShader.

QSGMaterialShader::Flags QSGMaterialShader::flags() const

Возвращает текущие установленные флаги для этого шейдера материала.

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

void QSGMaterialShader::setFlag(QSGMaterialShader::Flags flags, bool on = true)

Устанавливает флаги для данного шейдера материала, если on равно true; в противном случае сбрасывает указанные флаги.

void QSGMaterialShader::setFlags(QSGMaterialShader::Flags flags)

Устанавливает флаги для данного шейдера материала.

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

[protected] void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)

Устанавливает шейдер для указанной стадии.

[protected] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)

Устанавливает имя файла шейдера для указанной стадии.

Ожидается, что файл будет содержать сериализованный QShader.

[virtual] bool QSGMaterialShader::updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

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

Примечание: Эта функция вызывается только тогда, когда флаг UpdatesGraphicsPipelineState был установлен с помощью setFlags(). По умолчанию он не установлен, и поэтому эта функция никогда не вызывается.

Значение возврата должно быть true всякий раз, когда было внесено изменение в любой из элементов в ps.

Примечание: Содержимое ps не сохраняется между вызовами этой функции.

Текущее состояние отрисовки state передается из графического дерева сцены.

Состояние, специфичное для подкласса, может быть извлечено из newMaterial. Когда oldMaterial равно null, этот шейдер только что был активирован.

[virtual] void QSGMaterialShader::updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

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

binding — номер привязки образца. Функция вызывается для каждой переменной комбинированного образцового саплера в коде шейдера, связанного с QSGMaterialShader.

Когда *texture равно null, необходимо установить его в указатель QSGTexture перед возвратом. Если оно не равно null, материал сам решает, хранить ли новый QSGTexture * в нем или обновить некоторые параметры уже известного QSGTexture. Владение QSGTexture не передается.

Текущее состояние отрисовки state передается из графического дерева сцены. В соответствующих случаях материал сам отвечает за инициирование очереди загрузки данных текстуры.

Состояние, специфичное для подкласса, может быть извлечено из newMaterial.

oldMaterial может использоваться для минимизации изменений. Когда oldMaterial равно null, этот шейдер только что был активирован.

[virtual] bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

Эта функция вызывается графическим деревом сцены для обновления содержимого буфера униформ программы шейдера. Реализация не должна выполнять реальных графических операций, она просто отвечает за копирование данных в QByteArray, возвращаемый из RenderState::uniformData(). Графическое дерево сцены позаботится о том, чтобы этот буфер был виден в шейдерах.

Текущее состояние отрисовки state передается из графического дерева сцены. Если состояние указывает на то, что любое соответствующее состояние изменилось, реализация должна обновить соответствующий регион в данных буфера, доступных через RenderState::uniformData(). Если состояние, например, матрица или непрозрачность, не изменилось, нет необходимости затрагивать соответствующий регион, так как данные сохраняются.

Значение возврата должно быть true всякий раз, когда было внесено изменение в униформ-данные.

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

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