Класс QSGMaterialShader

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

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

Открытые типы

Открытые функции

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

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

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, Граф сцены — пользовательский материал, Граф сцены — два поставщика текстур и Граф сцены — граф.

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

перечисление QSGMaterialShader::FlagФлаги 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, этот шейдер только что был активирован.