Back to Qt.io
Contact Us Blog Download Qt
En esta página

QSGMaterialShader Class

La clase QSGMaterialShader representa un programa de sombreado independiente de la API gráfica. Más...

Cabecera: #include <QSGMaterialShader>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick

Tipos Públicos

struct GraphicsPipelineState
class RenderState
enum Flag { UpdatesGraphicsPipelineState }
flags Flags

Funciones Públicas

QSGMaterialShader()
(since 6.4) int combinedImageSamplerCount(int binding) const
QSGMaterialShader::Flags flags() const
void setFlag(QSGMaterialShader::Flags flags, bool on = true)
void setFlags(QSGMaterialShader::Flags flags)
virtual bool updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual void updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual bool updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

Funciones Protegidas

void setShader(QSGMaterialShader::Stage stage, const QShader &shader)
void setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)
(since 6.8) void setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

Descripción Detallada

QSGMaterialShader representa una combinación de sombreadores de vértices y fragmentos, datos que definen los cambios de estado del pipeline gráfico, y lógica que actualiza los recursos gráficos, como buffers uniformes y texturas.

Nota: Todas las clases con el prefijo QSG deben utilizarse únicamente en el subproceso de renderizado del gráfico de escena. Ver Gráfico de escena y renderizado para más información.

QSGMaterial y QSGMaterialShader forman una estrecha relación. Para un gráfico de escena (incluyendo gráficos anidados), hay una única instancia QSGMaterialShader que encapsula los shaders y otros datos que el gráfico de escena utiliza para renderizar un objeto con ese material. Cada QSGGeometryNode puede tener un único QSGMaterial que define cómo debe configurarse el pipeline gráfico mientras se dibuja el nodo. Una instancia de QSGMaterialShader nunca es creada explícitamente por el usuario, será creada bajo demanda por el gráfico de escena a través de QSGMaterial::createShader(). El gráfico de escena crea una instancia de QSGMaterialShader llamando al método QSGMaterial::createShader(), asegurando que sólo hay una instancia de cada implementación de shader.

En Qt 5, QSGMaterialShader estaba ligado a OpenGL. Estaba construido directamente sobre QOpenGLShaderProgram y tenía funciones como updateState() que podían emitir comandos OpenGL arbitrarios. Este ya no es el caso en Qt 6. QSGMaterialShader no está estrictamente orientado a datos, lo que significa que proporciona datos (shaders y los cambios de estado del pipeline deseados) junto con la lógica que actualiza los datos en un buffer uniforme. No proporciona acceso a la API gráfica. Esto significa que un QSGMaterialShader no puede hacer llamadas OpenGL, Vulkan, Metal o Direct 3D por sí mismo. Junto con la gestión unificada de shaders, esto permite que un QSGMaterialShader se escriba una vez, y sea funcional con cualquiera de las APIs gráficas soportadas en tiempo de ejecución.

Los sombreadores establecidos llamando a la función protegida setShaderFileName() controlan lo que el material hace con los datos de vértice de la geometría, y cómo los fragmentos son sombreados. Un QSGMaterialShader normalmente establecerá un vertex y un fragment shader durante la construcción. Cambiar los sombreadores después puede no conducir al efecto deseado y debe evitarse.

En Qt 6, el enfoque por defecto es enviar archivos .qsb con la aplicación, normalmente incrustados a través del sistema de recursos, y referenciados al llamar a setShaderFileName(). Los archivos .qsb se generan offline, o como muy tarde en el momento de compilar la aplicación, a partir del código fuente GLSL estilo Vulkan utilizando la herramienta qsb del módulo Qt Shader Tools.

Hay tres virtuales que pueden ser sobrescritos. Estos proporcionan los datos, o la lógica para generar los datos, para buffers uniformes, texturas, y cambios de estado en el pipeline.

updateUniformData() es la función más comúnmente reimplementada en subclases. Se espera que esta función actualice el contenido de un QByteArray que luego será expuesto a los shaders como un buffer uniforme. Cualquier QSGMaterialShader que tenga un bloque uniforme en su sombreador de vértices o fragmentos debe reimplementar updateUniformData().

updateSampledImage() es relevante cuando el código del shader muestrea texturas. La función será invocada para cada muestreador (o muestreador de imagen combinada, en las APIs donde sea relevante), dándole la opción de especificar qué QSGTexture debe ser expuesto al shader.

Los cambios de estado del shader pipeline se utilizan con menos frecuencia. Un caso de uso son los materiales que desean utilizar un modo de mezcla específico. La función relevante es updateGraphicsPipelineState(). Esta función no se llama a menos que el QSGMaterialShader ha optado por establecer la bandera UpdatesGraphicsPipelineState. La tarea de la función es actualizar la instancia GraphicsPipelineState struct que se le pasa con los cambios deseados. Actualmente sólo están disponibles las funciones relacionadas con blending y culling, otros estados no pueden ser controlados por materiales.

Un ejemplo mínimo, que también incluye soporte de texturas, podría ser el siguiente. Aquí asumimos que Material es el QSGMaterial que crea una instancia de Shader en su createShader(), y que contiene un QSGTexture que queremos muestrear en el fragment shader. El vertex shader sólo depende de la matriz modelview-projection.

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();
    }
};

El código fuente GLSL estilo Vulkan para los shaders podría tener el siguiente aspecto. Se espera que estos sean preprocesados offline usando la herramienta qsb, que genera los archivos .qsb referenciados en el constructor 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);
}

Nota: Todas las clases con el prefijo QSG deben ser utilizadas únicamente en el hilo de renderizado del gráfico de escena. Ver Gráfico de Escena y Renderizado para más información.

Ver también QSGMaterial, Gráfico de escena - Material personalizado, Gráfico de escena - Dos proveedores de texturas, y Gráfico de escena - Gráfico.

Documentación de tipos de miembros

enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags

Valores de bandera para indicar propiedades especiales del material.

ConstanteValorDescripción
QSGMaterialShader::UpdatesGraphicsPipelineState0x0001Establecer esta bandera permite llamar a updateGraphicsPipelineState().

El tipo Flags es un typedef para QFlags<Flag>. Almacena una combinación OR de valores Flag.

Documentación de las funciones miembro

QSGMaterialShader::QSGMaterialShader()

Construye un nuevo QSGMaterialShader.

[since 6.4] int QSGMaterialShader::combinedImageSamplerCount(int binding) const

Devuelve el número de elementos en la variable del muestreador de imagen combinada en binding. Este valor es introspeccionado desde el código del shader. La variable puede ser un array, y puede tener más de una dimensión.

El recuento refleja el número total de elementos del muestreador de imágenes combinadas en la variable. En el siguiente ejemplo, el recuento para srcA es 1, srcB es 4, y srcC es 6.

layout (binding = 0) uniform sampler2D srcA;
layout (binding = 1) uniform sampler2D srcB[4];
layout (binding = 2) uniform sampler2D srcC[2][3];

Este recuento es el número de punteros QSGTexture en el parámetro de textura de QSGMaterialShader::updateSampledImage.

Esta función se introdujo en Qt 6.4.

Véase también QSGMaterialShader::updateSampledImage.

QSGMaterialShader::Flags QSGMaterialShader::flags() const

Devuelve las banderas actualmente establecidas para este sombreador de material.

Véase también setFlags().

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

Establece el flags en este sombreador de material si on es verdadero; de lo contrario borra las banderas especificadas.

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

Establece el flags para este shader de material.

Ver también flags().

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

Establece el shader para el stage especificado.

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

Establece el filename del sombreador para el stage especificado.

Se espera que el archivo contenga un QShader serializado.

Advertencia: Se supone que los shaders, incluidos los archivos .qsb, son contenido de confianza. Se recomienda a los desarrolladores de aplicaciones que consideren cuidadosamente las posibles implicaciones antes de permitir la carga de contenido proporcionado por el usuario que no forme parte de la aplicación.

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

Establece el filename del sombreador para el stage especificado.

Se espera que el archivo contenga un QShader serializado.

Esta sobrecarga se utiliza cuando se habilita el renderizado de multiview, en particular cuando se utiliza la opción de conveniencia MULTIVIEW del sistema de compilación.

viewCount debe ser 2, 3 o 4. El filename se ajusta automáticamente en base a esto.

Advertencia: Se supone que los shaders, incluidos los archivos .qsb, son contenido de confianza. Se aconseja a los desarrolladores de aplicaciones que consideren cuidadosamente las implicaciones potenciales antes de permitir la carga de contenido proporcionado por el usuario que no forme parte de la aplicación.

Esta función se introdujo en Qt 6.8.

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

Esta función es llamada por el gráfico de escena para permitir que el material proporcione un conjunto personalizado de estados gráficos. El conjunto de estados que son personalizables por el material se limita a la mezcla y los ajustes relacionados.

Nota: Esta función sólo es llamada cuando la bandera UpdatesGraphicsPipelineState fue habilitada a través de setFlags(). Por defecto no está activada, por lo que nunca se llama a esta función.

El valor de retorno debe ser true siempre que se haya realizado un cambio en cualquiera de los miembros de ps.

Nota: El contenido de ps no es persistente entre invocaciones de esta función.

El renderizado actual state se pasa desde el gráfico de escena.

El estado específico de la subclase puede ser extraído de newMaterial. Cuando oldMaterial es null, este shader acaba de ser activado.

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

Esta función es llamada por el gráfico de escena para preparar el uso de imágenes muestreadas en el shader, típicamente en forma de muestreadores de imagen combinados.

binding es el número de enlace del muestreador. La función es llamada para cada variable de muestreador de imagen combinada en el código del shader asociado con QSGMaterialShader.

texture es una matriz de punteros QSGTexture. El número de elementos de la matriz coincide con el número de elementos de la variable del muestreador de imágenes especificada en el código del shader. Esta variable puede ser una matriz, y puede tener más de una dimensión. El número de elementos de la matriz se puede averiguar mediante QSGMaterialShader::combinedImageSamplerCount

Cuando un elemento de texture es nulo, debe establecerse a un puntero QSGTexture válido antes de devolver. Cuando no es nulo, depende del material decidir si se le almacena un nuevo QSGTexture *, o si actualiza algunos parámetros en el ya conocido QSGTexture. La propiedad del QSGTexture no se transfiere.

El renderizado actual state se pasa desde el gráfico de escena. Cuando sea relevante, depende del material activar la carga de datos de textura en cola a través de QSGTexture::commitTextureOperations().

El estado específico de la subclase puede extraerse de newMaterial.

oldMaterial se puede utilizar para minimizar los cambios. Cuando oldMaterial es null, este shader acaba de ser activado.

Ver también QSGMaterialShader::combinedImageSamplerCount.

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

Esta función es llamada por el gráfico de escena para obtener el contenido del buffer uniforme del programa de sombreado actualizado. No se espera que la implementación realice ninguna operación gráfica real, simplemente es responsable de copiar los datos a QByteArray devueltos por RenderState::uniformData(). El gráfico de escena se encarga de hacer visible ese buffer en los shaders.

El renderizado actual state se pasa desde el gráfico de escena. Si el estado indica que algún estado relevante está sucio, la implementación debe actualizar la región apropiada en los datos del buffer que es accesible a través de RenderState::uniformData(). Cuando un estado, como, matriz u opacidad, no está sucio, no hay necesidad de tocar la región correspondiente ya que los datos son persistentes.

El valor de retorno debe ser true siempre que se haya realizado algún cambio en los datos uniformes.

El estado específico de la subclase, como el color de un material de color plano, debe extraerse de newMaterial para actualizar en consecuencia las regiones pertinentes del búfer.

oldMaterial puede utilizarse para minimizar los cambios en el búfer (que suelen ser llamadas a memcpy) al actualizar los estados de los materiales. Cuando oldMaterial es null, este shader acaba de ser activado.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.