En esta página

QSGMaterial Class

La clase QSGMaterial encapsula el estado de renderizado de un programa de sombreado. Más información...

Encabezado: #include <QSGMaterial>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick
Heredado por:

QSGFlatColorMaterial, QSGOpaqueTextureMaterial y QSGVertexColorMaterial

Tipos públicos

enum Flag { Blending, RequiresDeterminant, RequiresFullMatrixExceptTranslate, RequiresFullMatrix, NoBatching, CustomCompileStep }
flags Flags

Funciones públicas

virtual int compare(const QSGMaterial *other) const
virtual QSGMaterialShader *createShader(QSGRendererInterface::RenderMode renderMode) const = 0
QSGMaterial::Flags flags() const
void setFlag(QSGMaterial::Flags flags, bool on = true)
virtual QSGMaterialType *type() const = 0
(since 6.8) int viewCount() const

Descripción detallada

QSGMaterialShader y las subclases de QSGMaterialShader mantienen una estrecha relación. Para cada grafo de escena (incluidos los grafos anidados), existe una única instancia de que encapsula los sombreadores que el grafo de escena utiliza para renderizar ese material, como por ejemplo un sombreador para el coloreado plano de la geometría. Cada « QSGGeometryNode » puede tener un «QSGMaterial» único que contiene la configuración que debe tener el sombreador al dibujar ese nodo, como el color real que se utilizará para renderizar la geometría.

QSGMaterial tiene dos funciones virtuales que deben implementarse ambas. La función type() debe devolver una instancia única para todas las instancias de una subclase específica. La función createShader() debe devolver una nueva instancia de QSGMaterialShader, específica para esa subclase de QSGMaterial.

Una implementación mínima de QSGMaterial podría tener este aspecto:

class Material : public QSGMaterial
{
public:
    QSGMaterialType *type() const override { static QSGMaterialType type; return &type; }
    QSGMaterialShader *createShader(QSGRendererInterface::RenderMode) const override { return new Shader; }
};

Consulta el ejemplo «Material personalizado» para obtener una introducción a la implementación de una subclase de ` QQuickItem ` respaldada por un ` QSGGeometryNode ` y un material personalizado.

Nota: createShader() solo se invoca una vez por cada QSGMaterialType, para reducir el trabajo redundante en la preparación de los shaders. Si un QSGMaterial está respaldado por varios conjuntos de combinaciones de shaders de vértices y de fragmentos, la implementación de type() debe devolver un puntero QSGMaterialType diferente y único para cada combinación de shaders.

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 « QSGMaterialShader» , «Grafo de escena: material personalizado», «Grafo de escena: dos proveedores de texturas» y «Grafo de escena: grafo».

Documentación sobre los tipos de miembros

enum QSGMaterial::Flag
flags QSGMaterial::Flags

ConstanteValorDescripción
QSGMaterial::Blending0x0001Establece este indicador en «true» si el material requiere que la mezcla esté habilitada durante el renderizado.
QSGMaterial::RequiresDeterminant0x0002Establece este indicador en «true» si el material depende del determinante de la matriz de los nodos geométricos para el renderizado.
QSGMaterial::RequiresFullMatrixExceptTranslate0x0004 | RequiresDeterminantEstablece este indicador en «true» si el material se basa en la matriz completa de los nodos de geometría para el renderizado, excepto la parte de traslación.
QSGMaterial::RequiresFullMatrix0x0008 | RequiresFullMatrixExceptTranslateEstablece este indicador en «true» si el material se basa en la matriz completa de los nodos de geometría para el renderizado.
QSGMaterial::NoBatching0x0010Establece este indicador en «true» si el material utiliza sombreadores incompatibles con el mecanismo de agrupamiento por lotes del grafo de escena. Esto es relevante en determinados usos avanzados, como la manipulación directa de « gl_Position.z » en el sombreador de vértices. Este tipo de soluciones suelen estar vinculadas a una estructura de escena específica y es probable que no sea seguro utilizarlas con contenidos arbitrarios en una escena. Por lo tanto, este indicador solo debe establecerse tras un análisis adecuado, y nunca será necesario para la gran mayoría de los materiales. Establecer este indicador puede provocar una reducción del rendimiento debido a que se deben emitir más llamadas de dibujo. Este indicador se introdujo en Qt 6.3.
QSGMaterial::CustomCompileStepNoBatchingEn Qt 6, este indicador es idéntico a NoBatching. Es preferible utilizar NoBatching en su lugar.

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

Documentación de las funciones miembro

[virtual] int QSGMaterial::compare(const QSGMaterial *other) const

Compara este material con other y devuelve 0 si son iguales; -1 si este material debe aparecer antes que other y 1 si other debe aparecer antes.

El grafo de escena puede reordenar los nodos geométricos para minimizar los cambios de estado. La función de comparación se invoca durante el proceso de ordenación, de modo que los materiales puedan ordenarse para minimizar los cambios de estado en cada llamada a QSGMaterialShader::updateState().

Se garantiza que el puntero «this» y « other » tienen el mismo valor de type().

[pure virtual] QSGMaterialShader *QSGMaterial::createShader(QSGRendererInterface::RenderMode renderMode) const

Esta función devuelve una nueva instancia de la implementación de « QSGMaterialShader » utilizada para renderizar la geometría de una implementación específica de « QSGMaterial ».

La función solo se llamará una vez por cada combinación de tipo de material y ` renderMode `, y se almacenará en caché internamente.

Para la mayoría de los materiales, el ` renderMode ` puede ignorarse. Algunos materiales pueden necesitar un tratamiento personalizado para modos de renderizado específicos. Por ejemplo, si el material implementa el suavizado de bordes (antialiasing) de una forma que debe tener en cuenta las transformaciones de perspectiva cuando se utiliza `RenderMode3D`.

QSGMaterial::Flags QSGMaterial::flags() const

Devuelve los indicadores del material.

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

Establece los indicadores « flags » en este material si « on » es verdadero; en caso contrario, borra el atributo.

[pure virtual] QSGMaterialType *QSGMaterial::type() const

El grafo de escena invoca esta función para consultar un identificador único de la instancia de QSGMaterialShader creada mediante createShader().

Para muchos materiales, el enfoque habitual consistirá en devolver un puntero a una instancia de ` QSGMaterialType ` estática y, por lo tanto, disponible a nivel global. El ` QSGMaterialType ` es un objeto opaco. Su única finalidad es servir como una forma sencilla y segura en cuanto a tipos de generar identificadores únicos de materiales.

QSGMaterialType *type() const override
{
    static QSGMaterialType type;
    return &type;
}

[since 6.8] int QSGMaterial::viewCount() const

Devuelve el número de vistas en caso de que el material se utilice en un renderizado multivista.

Nota: El valor devuelto solo es válido cuando se invoca desde ` createShader()` y posteriormente. El valor no está necesariamente actualizado antes de que el grafo de escena invoque a ` createShader()`.

Normalmente, el valor devuelto es 1. Un recuento de vistas superior a 2 implica una pasada de renderizado multivista. Se espera que los materiales compatibles con multivista consulten viewCount() en createShader() o en su constructor QSGMaterialShader, y se aseguren de que se seleccionan los shaders adecuados. A continuación, se espera que el shader de vértices utilice gl_ViewIndex para indexar la matriz de modelo-vista-proyección, ya que hay varias matrices en el modo multivista (una por cada vista).

A modo de ejemplo, consideremos el siguiente shader de vértices sencillo:

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
    mat4 matrix[2];
    float opacity;
};

void main()
{
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
    color = vertexColor * opacity;
}

Este sombreador está preparado para gestionar 2 vistas, y solo 2 vistas. No es compatible con otros números de vistas. Al condicionar el sombreador, hay que invocar la herramienta qsb con --view-count 2 o, si se utiliza la integración con CMake, hay que especificar VIEW_COUNT 2 en el comando qt_add_shaders().

Nota: qsb inserta automáticamenteuna línea con #extension GL_EXT_multiview : require siempre que se establezca un número de vistas igual o superior a 2.

Se recomienda a los desarrolladores que utilicen la variable de preprocesador QSHADER_VIEW_COUNT, que se inserta automáticamente, para simplificar la gestión de los diferentes números de vistas. Por ejemplo, si es necesario admitir tanto la opción sin vistas múltiples como la de vistas múltiples con un número de vistas igual a 2 en el mismo archivo fuente, se podría hacer lo siguiente:

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
#if QSHADER_VIEW_COUNT >= 2
    mat4 matrix[QSHADER_VIEW_COUNT];
#else
    mat4 matrix;
#endif
    float opacity;
};

void main()
{
#if QSHADER_VIEW_COUNT >= 2
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
#else
    gl_Position = matrix * vertexCoord;
#endif
    color = vertexColor * opacity;
}

Ahora, el mismo archivo fuente se puede procesar dos veces mediante qsb o qt_add_shaders(): una vez sin especificar el número de vistas y otra con el número de vistas establecido en 2. A continuación, el material puede seleccionar el archivo .qsb adecuado en función de viewCount() en tiempo de ejecución.

Con CMake, esto podría tener un aspecto similar al siguiente. En este ejemplo, se espera que el archivo « QSGMaterialShader » correspondiente elija entre « :/shaders/example.vert.qsb » y « :/shaders/multiview/example.vert.qsb » en función del valor de viewCount(). (Lo mismo se aplica al sombreador de fragmentos)

qt_add_shaders(application "application_shaders"
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

qt_add_shaders(application "application_multiview_shaders"
    GLSL
        330,300es
    HLSL
        61
    MSL
        12
    VIEW_COUNT
        2
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
    OUTPUTS
        shaders/multiview/example.vert
        shaders/multiview/example.frag
)

Nota: El sombreador de fragmentos debe tratarse de la misma forma que el sombreador de vértices, aunque el código del sombreador de fragmentos no pueda tener ninguna dependencia del recuento de vistas (gl_ViewIndex), para garantizar la máxima portabilidad. Hay dos razones para incluir también los sombreadores de fragmento en el conjunto multivista. Una es que mezclar diferentes versiones de sombreadores dentro de la misma tubería gráfica puede resultar problemático, dependiendo de la API gráfica subyacente: con D3D12, por ejemplo, mezclar sombreadores HLSL para los modelos de sombreador 5.0 y 6.1 generaría un error. La otra es que disponer de « QSHADER_VIEW_COUNT » definido en los sombreadores de fragmento puede resultar muy útil, por ejemplo, al compartir una disposición de búfer uniforme entre las etapas de vértices y de fragmentos.

Nota: En OpenGL, la versión mínima de GLSL para los sombreadores de vértices que utilizan « gl_ViewIndex » es « 330 ». Es posible que se acepten versiones inferiores en el momento de la compilación, pero pueden provocar un error en tiempo de ejecución, dependiendo de la implementación de OpenGL.

Para mayor comodidad, también existe una opción ` MULTIVIEW ` para `qt_add_shaders()`. Esta ejecuta primero la herramienta ` qsb ` de forma normal; a continuación, sobrescribe ` VIEW_COUNT ` por ` 2`, establece ` GLSL`, ` HLSL` y ` MSL ` con unos valores por defecto adecuados, y vuelve a ejecutar ` qsb `, esta vez generando archivos `.qsb` con un sufijo añadido. La implementación del material puede entonces utilizar la sobrecarga de QSGMaterialShader::setShaderFileName() que toma un argumento de tipo viewCount, el cual selecciona automáticamente el archivo .qsb correcto.

Por lo tanto, lo siguiente es prácticamente equivalente a la llamada de ejemplo mostrada anteriormente, salvo que no es necesario especificar ningún archivo de salida gestionado manualmente. Ten en cuenta que puede haber casos en los que las versiones del lenguaje de sombreado elegidas automáticamente no sean suficientes; en tal caso, las aplicaciones deberían seguir especificándolo todo de forma explícita.

qt_add_shaders(application "application_multiview_shaders"
    MULTIVIEW
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

Consulte QRhi::MultiView, QRhiColorAttachment::setMultiViewCount() y QRhiGraphicsPipeline::setMultiViewCount() para obtener más detalles de bajo nivel sobre la compatibilidad con vistas múltiples en Qt. El renderizador de grafos de escena Qt Quick está preparado para reconocer destinos de renderizado de vistas múltiples, cuando se especifican mediante QQuickRenderTarget::fromRhiRenderTarget() o las funciones específicas de la API 3D, como fromVulkanImage() con un argumento arraySize mayor que 1. A continuación, el renderizador propagará el recuento de vistas a los flujos de trabajo gráficos y a los materiales.

Esta función se introdujo en Qt 6.8.

© 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.