QSGMaterialShader Class
La clase QSGMaterialShader representa un programa de sombreado independiente de la API gráfica. Más información...
| Encabezado: | #include <QSGMaterialShader> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
- Lista de todos los miembros, incluidos los heredados
- QSGMaterialShader forma parte de las clases de materiales del grafo de escena deQt 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 de fragmentos, datos que definen los cambios de estado del canal de procesamiento gráfico y la lógica que actualiza los recursos gráficos, como los búferes uniformes y las texturas.
Nota: Todas las clases con el prefijo QSG deben utilizarse exclusivamente en el hilo de renderizado del grafo de escena. Consulta «Grafo de escena y renderizado» para obtener más información.
QSGMaterial y QSGMaterialShader mantienen una estrecha relación. Para cada grafo de escena (incluidos los grafos anidados), existe una única instancia de `QSGMaterialShader` que encapsula los sombreadores y otros datos que el grafo de escena utiliza para renderizar un objeto con ese material. Cada ` QSGGeometryNode ` puede tener un único ` QSGMaterial ` que define cómo debe configurarse el canal gráfico al dibujar el nodo. El usuario nunca crea explícitamente una instancia de `QSGMaterialShader`; esta la crea el grafo de escena bajo demanda mediante ` QSGMaterial::createShader()`. El grafo de escena crea una instancia de `QSGMaterialShader` llamando al método ` QSGMaterial::createShader()`, lo que garantiza que solo haya una instancia de cada implementación de shader.
En Qt 5, QSGMaterialShader estaba vinculado a OpenGL. Se basaba directamente en ` QOpenGLShaderProgram ` y contaba con funciones como ` updateState() ` que podían emitir comandos OpenGL arbitrarios. Esto ya no es así en Qt 6. QSGMaterialShader no está estrictamente orientado a datos, lo que significa que proporciona datos (shaders y los cambios de estado deseados en el pipeline) junto con la lógica que actualiza los datos en un búfer uniforme. No se proporciona acceso a la API gráfica. Esto significa que un QSGMaterialShader no puede realizar llamadas a 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 sola vez y sea funcional con cualquiera de las API gráficas compatibles en tiempo de ejecución.
Los sombreadores establecidos mediante la llamada a la función protegida ` setShaderFileName()` controlan lo que hace el material con los datos de vértices de la geometría y cómo se sombrean los fragmentos. Normalmente, un `QSGMaterialShader` establecerá un sombreador de vértices y un sombreador de fragmentos durante su construcción. Cambiar los sombreadores posteriormente puede no producir el efecto deseado y debe evitarse.
En Qt 6, el enfoque predeterminado consiste en incluir los archivos ` .qsb ` con la aplicación, normalmente integrados a través del sistema de recursos, y a los que se hace referencia al llamar a ` setShaderFileName()`. Los archivos ` .qsb ` se generan fuera de línea, o como muy tarde en el momento de la compilación de la aplicación, a partir de código fuente GLSL al estilo Vulkan utilizando la herramienta ` qsb ` del módulo ` Shader Tools ` de Qt XML.
Hay tres métodos virtuales que se pueden sobrescribir. Estos proporcionan los datos, o la lógica para generar los datos, para los búferes uniformes, las texturas y los cambios de estado del canal de procesamiento.
updateUniformData() es la función que se reimplementa con mayor frecuencia en las subclases. Se espera que esta función actualice el contenido de un ` QByteArray `, que posteriormente se expondrá a los shaders como un búfer uniforme. Cualquier `QSGMaterialShader` que tenga un bloque uniforme en su shader de vértices o de fragmentos debe reimplementar ` updateUniformData()`.
updateSampledImage() es relevante cuando el código del sombreador muestrea texturas. La función se invocará para cada muestreador (o muestreador de imagen combinada, en las API donde sea pertinente), dándole la opción de especificar qué ` QSGTexture ` debe exponerse al sombreador.
Los cambios en el estado de la canalización del sombreador se utilizan con menos frecuencia. Un caso de uso son los materiales que desean utilizar un modo de fusión específico. La función relevante es ` updateGraphicsPipelineState()`. Esta función no se invoca a menos que el `QSGMaterialShader` lo haya habilitado estableciendo el indicador ` UpdatesGraphicsPipelineState`. La tarea de la función es actualizar la instancia de la estructura ` GraphicsPipelineState ` que se le pasa con los cambios deseados. Actualmente solo están disponibles las funciones relacionadas con la mezcla y el culling; los materiales no pueden controlar otros estados.
Un ejemplo mínimo, que también incluye soporte para texturas, podría ser el siguiente. Aquí suponemos que `Material` es el ` QSGMaterial ` que crea una instancia de `Shader` en su ` createShader()` y que contiene un ` QSGTexture ` que queremos muestrear en el sombreador de fragmentos. El sombreador de vértices se basa únicamente en la matriz de proyección modelo-vista.
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 al estilo Vulkan para los sombreadores podría tener el siguiente aspecto. Se espera que estos se preprocesen fuera de línea utilizando la herramienta qsb, que genera los archivos .qsb a los que hace referencia el constructor de 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 utilizarse exclusivamente en el hilo de renderizado del grafo de escena. Consulta «Grafo de escena y renderizado» para obtener más información.
Véase 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 sobre tipos de miembros
enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags
Valores de indicador para señalar propiedades especiales de los materiales.
| Constante | Valor | Descripción |
|---|---|---|
QSGMaterialShader::UpdatesGraphicsPipelineState | 0x0001 | Al activar este indicador, se permite llamar a ` updateGraphicsPipelineState()`. |
El tipo Flags es un typedef para QFlags<Flag>. Almacena una combinación OR de valores de Flag.
Documentación de las funciones miembro
QSGMaterialShader::QSGMaterialShader()
Crea un nuevo QSGMaterialShader.
[since 6.4] int QSGMaterialShader::combinedImageSamplerCount(int binding) const
Devuelve el número de elementos de la variable de muestreador de imagen combinada en binding. Este valor se obtiene mediante introspección del código del shader. La variable puede ser una matriz y puede tener más de una dimensión.
El recuento refleja el número total de elementos del muestreador de imagen combinado que hay en la variable. En el siguiente ejemplo, el recuento para srcA es 1, para srcB es 4 y para 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 corresponde al número de punteros QSGTexture presentes 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 los indicadores activados actualmente para este sombreador de material.
Véase también setFlags().
void QSGMaterialShader::setFlag(QSGMaterialShader::Flags flags, bool on = true)
Establece la opción « flags » en este sombreador de material si « on » es «true»; en caso contrario, desactiva los indicadores especificados.
void QSGMaterialShader::setFlags(QSGMaterialShader::Flags flags)
Establece el valor de « flags » para este sombreador de material.
Véase también flags().
[protected] void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)
Establece el valor de « shader » para el elemento « 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 considera quelos sombreadores , incluidos los archivos « .qsb », son contenido de confianza. Se recomienda a los desarrolladores de aplicaciones que evalúen 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 al habilitar 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 función de este valor.
Advertencia: Se da por supuesto quelos 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.
Esta función se introdujo en Qt 6.8.
[virtual] bool QSGMaterialShader::updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
El grafo de escena invoca esta función para permitir que el material proporcione un conjunto personalizado de estados gráficos. El conjunto de estados que se pueden personalizar por material se limita a la mezcla y a los ajustes relacionados.
Nota: Esta función solo se invoca cuando se ha habilitado el indicador « UpdatesGraphicsPipelineState » mediante la función setFlags(). Por defecto, no está activado, por lo que esta función nunca se invoca.
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 se conserva entre las invocaciones de esta función.
El renderizado actual ` state ` se pasa desde el grafo de escena.
El estado específico de la subclase se puede extraer de ` newMaterial`. Cuando ` oldMaterial ` es nulo, este sombreador acaba de activarse.
[virtual] void QSGMaterialShader::updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
El grafo de escena invoca esta función para preparar el uso de imágenes muestreadas en el sombreador, normalmente en forma de muestreadores de imágenes combinados.
binding es el número de enlace del muestreador. La función se invoca para cada variable de muestreador de imagen combinado en el código del sombreador asociada a ` QSGMaterialShader`.
texture es una matriz de punteros a ` QSGTexture `. El número de elementos de la matriz coincide con el número de elementos de la variable de muestreador de imagen 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 obtener mediante QSGMaterialShader::combinedImageSamplerCount
Cuando un elemento de ` texture ` es nulo, debe establecerse como un puntero válido a ` QSGTexture ` antes de devolverlo. Cuando no es nulo, corresponde al material decidir si se almacena en él un nuevo ` QSGTexture * `, o si se actualizan algunos parámetros del ` QSGTexture` ya conocido. La propiedad de ` QSGTexture ` no se transfiere.
El renderizado actual state se pasa desde el grafo de escena. Cuando sea pertinente, corresponde al material activar la puesta en cola de las cargas de datos de textura mediante QSGTexture::commitTextureOperations().
El estado específico de la subclase se puede extraer de ` newMaterial`.
oldMaterial Se puede utilizar para minimizar los cambios. Cuando oldMaterial es nulo, este sombreador acaba de activarse.
Véase también QSGMaterialShader::combinedImageSamplerCount.
[virtual] bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
El grafo de escena invoca esta función para actualizar el contenido del búfer de uniformes del programa de sombreado. No se espera que la implementación realice ninguna operación gráfica real, sino que se limita a copiar datos a la dirección QByteArray devuelta por la función ` RenderState::uniformData()`. El grafo de escena se encarga de hacer que ese búfer sea visible en los sombreadores.
El « state » de renderizado actual se pasa desde el grafo de escena. Si el estado indica que algún estado relevante está «sucio», la implementación debe actualizar la región correspondiente en los datos del búfer a los que se accede mediante RenderState::uniformData(). Cuando un estado, como por ejemplo una matriz o la opacidad, no está «sucio», no es necesario modificar 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 las regiones pertinentes del búfer en consecuencia.
oldMaterial Se puede utilizar para minimizar los cambios en el búfer (que suelen ser llamadas a `memcpy`) al actualizar los estados de los materiales. Cuando ` oldMaterial ` es nulo, significa que este sombreador acaba de activarse.
© 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.