ShaderEffect QML Type
Aplica sombreadores personalizados a un rectángulo. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- blending : bool
- cullMode : enumeration
- fragmentShader : url
- log : string
- mesh : variant
- status : enumeration
- supportsAtlasTextures : bool
(since QtQuick 2.4) - vertexShader : url
Descripción detallada
El tipo ShaderEffect aplica un sombreador personalizado de tipo « vertex » y « fragment (pixel) » a un rectángulo. Permite añadir efectos como sombra proyectada, desenfoque, coloración y efecto de página curvada a la escena QML.
Nota: Dependiendo del backend de scenegraph de Qt Quick que se utilice, es posible que el tipo ShaderEffect no sea compatible. Por ejemplo, con el backend software, los efectos no se renderizarán en absoluto.
Sombreadores
En Qt 5, los efectos se proporcionaban en forma de código fuente GLSL (OpenGL Shading Language), a menudo incrustado como cadenas en QML. A partir de Qt 5.8, también pasó a ser posible hacer referencia a archivos, ya fueran locales o del sistema de recursos de Qt.
En Qt 6, Qt Quick también es compatible con API gráficas como Vulkan, Metal y Direct3D 11. Por lo tanto, ya no es viable trabajar con cadenas de código fuente GLSL. En su lugar, el nuevo proceso de sombreado se basa en la compilación de código GLSL compatible con Vulkan a SPIR-V, seguida de la recopilación de información de reflexión y la traducción a otros lenguajes de sombreado, como HLSL, el lenguaje de sombreado de Metal y diversas versiones de GLSL. Los recursos resultantes se agrupan en un único paquete, que suele almacenarse en archivos con la extensión .qsb. Este proceso se lleva a cabo sin conexión o, a más tardar, en el momento de la compilación de la aplicación. En tiempo de ejecución, el grafo de escena y la abstracción gráfica subyacente utilizan estos archivos .qsb. Por lo tanto, ShaderEffect espera referencias a archivos (locales o qrc) en Qt 6 en lugar de código de sombreador en línea.
Las propiedades « vertexShader » y « fragmentShader » son URL en Qt 6 y funcionan de manera muy similar a « Image.source », por ejemplo. Sin embargo, ShaderEffect solo admite los esquemas « file » y « qrc ». También es posible omitir el esquema « file », lo que permite especificar una ruta relativa de forma cómoda. Dicha ruta se resuelve en relación con la ubicación del componente (el archivo « .qml »).
Entradas y recursos del shader
Hay dos tipos de entradas para el « vertexShader »: uniformes y entradas de vértice.
Las siguientes entradas están predefinidas:
- vec4 qt_Vertex con ubicación 0: posición de vértice; el vértice superior izquierdo tiene posición (0, 0) y el inferior derecho (width, height).
- vec2 qt_MultiTexCoord0 en la posición 1: coordenada de textura; la coordenada superior izquierda es (0, 0) y la inferior derecha (1, 1). Si supportsAtlasTextures es verdadero, las coordenadas se basarán en la posición en el atlas.
Nota: En la práctica, solo importa la ubicación de entrada del vértice. Los nombres se pueden cambiar libremente, mientras que la ubicación debe ser siempre 0 para la posición del vértice y 1 para las coordenadas de textura. Sin embargo, hay que tener en cuenta que esto solo se aplica a las entradas de vértices y no es necesariamente válido para las variables de salida del sombreador de vértices que luego se utilizan como entradas en el sombreador de fragmentos (normalmente, las coordenadas de textura interpoladas).
Las siguientes variables uniformes están predefinidas:
- mat4 qt_Matrix: matriz de transformación combinada, el producto de las matrices desde el elemento raíz hasta este ShaderEffect, y una proyección ortogonal.
- float qt_Opacity: opacidad combinada, el producto de las opacidades desde el elemento raíz hasta este ShaderEffect.
Nota: El GLSLal estilo Vulkan no tiene variables uniformes independientes. En su lugar, los shaders deben utilizar siempre un bloque «uniform» con un punto de enlace « 0 ».
Nota: El calificador de disposición del bloque «uniform» debe ser siempre « std140 ».
Nota: A diferencia de las entradas de vértices, los nombres predefinidos (qt_Matrix, qt_Opacity) no deben modificarse.
Además, cualquier propiedad que pueda asignarse a un tipo GLSL puede ponerse a disposición de los sombreadores. La siguiente lista muestra cómo se asignan las propiedades:
- bool, int, qreal -> bool, int, float: si el tipo en el sombreador no es el mismo que en QML, el valor se convierte automáticamente.
- QColor -> vec4: cuando se pasan colores al shader, primero se premultiplican. Así, Qt.rgba(0.2, 0.6, 1.0, 0.5) se convierte en vec4(0.1, 0.3, 0.5, 0.5) en el sombreador, por ejemplo.
- QRect, QRectF -> vec4 - Qt.rect(x, y, w, h) se convierte en vec4(x, y, w, h) en el shader.
- QPoint, QPointF, QSize, QSizeF → vec2
- QVector3D -> vec3
- QVector4D -> vec4
- QTransform -> mat3
- QMatrix4x4 -> mat4
- QQuaternion -> vec4; el valor escalar es
w. - Image -> sampler2D: el origen se encuentra en la esquina superior izquierda y los valores de color están premultiplicados. La textura se proporciona tal cual, sin incluir el modo de relleno (fillMode) del elemento Image. Para incluir el modo de relleno, utiliza un ShaderEffectSource o Image::layer::enabled.
- ShaderEffectSource -> sampler2D: el origen se encuentra en la esquina superior izquierda y los valores de color están premultiplicados.
Los muestreadores siguen declarándose como variables uniformes independientes en el código del shader. Los shaders pueden elegir libremente cualquier punto de enlace para ellos, excepto 0, ya que está reservado para el bloque uniform.
Algunos lenguajes de sombreado y API tienen un concepto de objetos de imagen y muestreador separados. Qt Quick siempre funciona con objetos combinados de imagen y muestreador en los sombreadores, tal y como admite SPIR-V. Por lo tanto, los sombreadores proporcionados para ShaderEffect siempre deben utilizar declaraciones de muestreadores al estilo de layout(binding = 1) uniform sampler2D tex;. La capa de abstracción subyacente y el proceso de renderizado se encargan de que esto funcione para todas las API y lenguajes de sombreado compatibles, de forma transparente para las aplicaciones.
El back-end del grafo de escena QML puede optar por asignar texturas en atlas de texturas. Si se pasa a un ShaderEffect una textura asignada en un atlas, por defecto se copia desde el atlas de texturas a una textura independiente, de modo que las coordenadas de textura abarcan de 0 a 1 y se obtienen los modos de envoltura esperados. Sin embargo, esto aumentará el consumo de memoria. Para evitar la copia de la textura, configura ` supportsAtlasTextures ` para shaders simples utilizando `qt_MultiTexCoord0`, o bien, para cada «uniform sampler2D <nombre>», declara un «uniform vec4 qt_SubRect_<nombre>» al que se le asignará el rectángulo de origen normalizado de la textura. Para texturas independientes, el rectángulo de origen es [0, 1]x[0, 1]. Para texturas en un atlas, el rectángulo de origen se corresponde con la parte del atlas de texturas donde se almacena la textura. La forma correcta de calcular la coordenada de textura para una textura denominada «source» dentro de un atlas de texturas es «qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0».
La salida de « fragmentShader » debe estar premultiplicada. Si se habilita « blending », se utiliza la mezcla «source-over». Sin embargo, se puede lograr una mezcla aditiva emitiendo un cero en el canal alfa.
| |
El ejemplo da por hecho que « myeffect.vert » y « myeffect.frag » contienen código GLSL al estilo de Vulkan, procesado por la herramienta « qsb » para generar los archivos « .qsb ».
#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
mat4 qt_Matrix;
float qt_Opacity;
};
void main() {
coord = qt_MultiTexCoord0;
gl_Position = qt_Matrix * qt_Vertex;
}#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
mat4 qt_Matrix;
float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
vec4 tex = texture(src, coord);
fragColor = vec4(vec3(dot(tex.rgb, vec3(0.344, 0.5, 0.156))), tex.a) * qt_Opacity;
}Nota: Las texturas del grafode escena tienen su origen en la esquina superior izquierda, en lugar de en la inferior izquierda, como es habitual en OpenGL.
Cuando solo hay un shader
No es obligatorio especificar tanto vertexShader como fragmentShader. En la práctica, muchas implementaciones de ShaderEffect solo proporcionarán un sombreador de fragmentos, mientras que se basarán en el sombreador de vértices predeterminado e integrado.
El sombreador de vértices predeterminado pasa la coordenada de textura al sombreador de fragmentos como ` vec2 qt_TexCoord0 ` en la ubicación ` 0`.
El sombreador de fragmentos predeterminado espera que el sombreador de vértices le pase la coordenada de textura como « vec2 qt_TexCoord0 » en la ubicación 0, y la muestrea desde un «sampler2D» denominado « source » en el punto de enlace 1.
Advertencia: Cuando solo se especifica uno de los sombreadores, el autor del sombreador debe tener en cuenta la disposición del bloque de uniformes que esperan los sombreadores predeterminados: qt_Matrix debe estar siempre en el desplazamiento 0, seguido de qt_Opacity en el desplazamiento 64. Cualquier uniforme personalizado debe colocarse después de estos dos. Esto es obligatorio incluso cuando el shader proporcionado por la aplicación no utilice la matriz ni la opacidad, ya que en tiempo de ejecución hay un único búfer uniforme al que tienen acceso tanto el shader de vértices como el de fragmentos.
Advertencia: A diferencia de lo que ocurre con las entradas de vértices, el paso de datos entre el shader de vértices y el de fragmentos puede requerir, dependiendo de la API gráfica subyacente, que se utilicen los mismos nombres; una ubicación coincidente no siempre es suficiente. En particular, al especificar un sombreador de fragmentos mientras se utiliza el sombreador de vértices predeterminado e integrado, las coordenadas de textura se pasan como « qt_TexCoord0 » en la ubicación « 0 », por lo que se recomienda encarecidamente que el sombreador de fragmentos declare la entrada con el mismo nombre (qt_TexCoord0). De no hacerlo, pueden surgir problemas en algunas plataformas, por ejemplo, al ejecutarse con un contexto OpenGL de perfil no básico, en el que el código fuente del sombreador GLSL subyacente carece de calificadores de ubicación y la correspondencia se basa en los nombres de las variables durante el proceso de vinculación del sombreador.
ShaderEffect y capas de elementos
El tipo ShaderEffect se puede combinar con un layered items.
Capa con el efecto desactivado ![]() | Capa con efecto activado ![]() |
|
También es posible combinar varios elementos en capas:
![]() |
|
Otras notas
Por defecto, el ShaderEffect consta de cuatro vértices, uno por cada esquina. Para transformaciones de vértices no lineales, como el efecto de página doblada, puedes especificar una malla fina de vértices indicando una resolución de « mesh ».
Migración desde Qt 5
Para las aplicaciones de Qt 5 que utilicen elementos ShaderEffect, la migración a Qt 6 implica:
- Trasladar el código del shader a archivos independientes «
.vert» y «.frag», - actualizar los shaders a GLSL compatible con Vulkan,
- ejecutar la herramienta
qsbsobre ellos, - incluir los archivos
.qsbresultantes en el ejecutable mediante el sistema de recursos de Qt, - y hacer referencia al archivo en las propiedades vertexShader y fragmentShader.
Tal y como se describe en el módulo Qt Shader Tools, algunos de estos pasos se pueden automatizar haciendo que CMake invoque la herramienta qsb en el momento de la compilación. Consulte qt_add_shaders() para obtener más información y ejemplos.
En lo que respecta a la actualización del código del shader, a continuación se ofrece una visión general de los cambios que suelen ser necesarios.
| Shader de vértices en Qt 5 | Shader de vértices en Qt 6 |
|---|---|
| |
El proceso de conversión consiste principalmente en actualizar el código para que sea compatible con GL_KHR_vulkan_glsl. Cabe señalar que Qt Quick utiliza un subconjunto de las características que ofrecen GLSL y Vulkan, por lo que el proceso de conversión de los shaders típicos de ShaderEffect suele ser sencillo.
- La directiva `
version` debe indicar `440` o `450`, aunque especificar otra versión de GLSL también puede funcionar, ya que la extensión `GL_KHR_vulkan_glsl ` está escrita para GLSL 140 y versiones posteriores. - Las entradas y salidas deben utilizar las palabras clave modernas de GLSL «
in» y «out». Además, es obligatorio especificar una ubicación. Los espacios de nombres de las ubicaciones de entrada y salida son independientes, por lo que es seguro asignar ubicaciones a partir de 0 para ambos. - En lo que respecta a las entradas del sombreador de vértices, las únicas posibilidades con ShaderEffect son la ubicación
0para la posición de los vértices (denominada tradicionalmenteqt_Vertex) y la ubicación1para las coordenadas de textura (denominada tradicionalmenteqt_MultiTexCoord0). - Las salidas del sombreador de vértices y las entradas del sombreador de fragmentos deben definirse en el código del sombreador. El sombreador de fragmentos debe tener una salida «
vec4» en la ubicación 0 (denominada habitualmente «fragColor»). Para lograr la máxima portabilidad, las salidas del sombreador de vértices y las entradas del sombreador de fragmentos deben utilizar tanto el mismo número de ubicación como el mismo nombre. Cuando solo se especifica un sombreador de fragmentos, las coordenadas de textura se pasan desde el sombreador de vértices integrado como «vec2 qt_TexCoord0» en la ubicación «0», tal y como se muestra en los fragmentos de código de ejemplo anteriores. - Las variables uniformes fuera de un bloque «uniform» no son válidas. Por el contrario, los datos uniformes deben declararse en un bloque «uniform» con el punto de enlace
0. - Se espera que el bloque «uniform» utilice el calificador «std140».
- En tiempo de ejecución, los sombreadores de vértices y de fragmentos obtendrán el mismo búfer uniforme vinculado al punto de enlace 0. Por lo tanto, como regla general, las declaraciones del bloque «uniform» deben ser idénticas entre los sombreadores. Esto incluye también a los miembros que no se utilicen en uno de los sombreadores. Los nombres de los miembros deben coincidir, ya que en algunas API gráficas el bloque «uniform» se convierte en una estructura «uniform» tradicional, de forma transparente para la aplicación.
- Al proporcionar solo uno de los sombreadores, hay que tener en cuenta que los sombreadores integrados esperan encontrar «
qt_Matrix» y «qt_Opacity» al principio del bloque de uniformes (más concretamente, en los desplazamientos 0 y 64, respectivamente). Como regla general, inclúyalos siempre como primer y segundo miembro del bloque. - En el ejemplo, el bloque «uniform» especifica el nombre de bloque «
buf». Este nombre se puede cambiar libremente, pero debe coincidir entre los shaders. El uso de un nombre de instancia, como «layout(...) uniform buf { ... } instance_name;», es opcional. Cuando se especifica, todos los accesos a los miembros deben ir precedidos de «instance_name».
| Shader de fragmentos en Qt 5 | Shader de fragmentos en Qt 6 |
|---|---|
| |
- Los calificadores de precisión (
lowp,mediump,highp) no se utilizan actualmente. - La llamada a funciones GLSL integradas debe seguir la nomenclatura moderna de GLSL; en particular, «
texture()» en lugar de «texture2D()». - Los muestreadores deben utilizar puntos de enlace que empiecen por 1.
- Cuando Qt Quick se está renderizando con
multiviewhabilitado —por ejemplo, porque forma parte de una escena 3D que se renderiza en un entorno de RV/RA en el que el contenido para el ojo izquierdo y el derecho se genera en una sola pasada—, los shaders de ShaderEffect deben escribirse teniendo esto en cuenta. Con un recuento de vistas de 2, por ejemplo, habrá matrices de tipo «2» (qt_Matrix es una matriz de tipo mat4 con dos elementos). Se espera que el sombreador de vértices tenga en cuenta «gl_ViewIndex». Consulte la sección «Multiview» del Manual de QSB para obtener información general sobre la creación de sombreadores compatibles con múltiples vistas.
Véase también Item Layers, el Manual de QSB y qt_add_shaders.
Documentación de propiedades
blending : bool
Si esta propiedad tiene el valor «true», la salida del « fragmentShader » se fusiona con el fondo utilizando el modo de fusión «source-over». Si tiene el valor «false», no se tiene en cuenta el fondo. La fusión reduce el rendimiento, por lo que se recomienda establecer esta propiedad en «false» cuando no sea necesaria. El valor predeterminado es «true».
cullMode : enumeration
Esta propiedad define qué lados del elemento deben estar visibles.
| Constante | Descripción |
|---|---|
ShaderEffect.NoCulling | Ambos lados son visibles |
ShaderEffect.BackFaceCulling | solo se ve la parte delantera |
ShaderEffect.FrontFaceCulling | solo es visible la parte trasera |
El valor por defecto es NoCulling.
fragmentShader : url
Esta propiedad contiene una referencia a un archivo con el paquete de shaders de fragmentos preprocesado, normalmente con la extensión « .qsb ». El valor se trata como un « URL », de forma similar a otros tipos de QML, como «Image». Debe ser un archivo local o utilizar el esquema «qrc» para acceder a archivos incrustados a través del sistema de recursos de Qt. La URL puede ser absoluta o relativa a la URL del componente.
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.
Véase también vertexShader.
log : string [read-only]
Esta propiedad contiene un registro de advertencias y errores del último intento de compilación de los shaders. Se actualiza al mismo tiempo que se establece el valor de « status » en «Compiled» o «Error».
Nota: En Qt 6, el pipeline de shaders favorece la compilación y traducción de los shaders GLSL de estilo Vulkan fuera de línea, o como muy tarde en el momento de la compilación. Esto no significa necesariamente que no se produzca ninguna compilación de sombreadores en tiempo de ejecución, pero, aunque se produzca, « ShaderEffect » no interviene en ella, y ya no deberían producirse errores de sintaxis ni similares en esa fase. Por lo tanto, el valor de esta propiedad suele estar vacío.
Véase también status.
mesh : variant
Esta propiedad define la malla que se utiliza para dibujar el « ShaderEffect ». Puede contener cualquier objeto « GridMesh ». Si se asigna un valor de tamaño a esta propiedad, el « ShaderEffect » utiliza implícitamente un « GridMesh » con el valor « mesh resolution ». Por defecto, esta propiedad tiene un tamaño de 1x1.
Véase también GridMesh.
status : enumeration [read-only]
Esta propiedad indica el estado actual de los shaders.
| Constante | Descripción |
|---|---|
ShaderEffect.Compiled | El programa de sombreador se ha compilado y enlazado correctamente. |
ShaderEffect.Uncompiled | El programa de sombreado aún no se ha compilado. |
ShaderEffect.Error | El programa de shader no se ha podido compilar ni enlazar. |
Al configurar el código fuente del sombreador de fragmentos o de vértices, el estado pasará a ser «Sin compilar». La primera vez que se renderiza el « ShaderEffect » con un nuevo código fuente de sombreador, los sombreadores se compilan y enlazan, y el estado se actualiza a «Compilado» o «Error».
Cuando no se utiliza la compilación en tiempo de ejecución y las propiedades del shader hacen referencia a archivos con código byte, el estado es siempre «Compilado». El contenido del sombreador no se examina (aparte de la reflexión básica para detectar elementos de entrada de vértices y datos del búfer constante) hasta más adelante en el proceso de renderizado, por lo que los posibles errores (como discrepancias en la disposición o en la firma raíz) solo se detectarán en un momento posterior.
Véase también log.
supportsAtlasTextures : bool [since QtQuick 2.4]
Establece esta propiedad en «true» para confirmar que el código de tu shader no depende de que qt_MultiTexCoord0 tenga un rango comprendido entre (0,0) y (1,1) en relación con la malla. En este caso, el rango de `qt_MultiTexCoord0` se basará más bien en la posición de la textura dentro del atlas. Actualmente, esta propiedad no tiene ningún efecto si se utiliza menos de un uniforme de muestreo, o más de uno, como entrada para tu sombreador.
Esto difiere de proporcionar uniformes qt_SubRect_<nombre> en que estos últimos permiten dibujar una o más texturas del atlas en un único elemento « ShaderEffect », mientras que «supportsAtlasTextures» permite que múltiples instancias de un componente « ShaderEffect » que utilicen una imagen de origen diferente del atlas se agrupen en un único dibujo. Ambas opciones evitan que una textura se copie fuera del atlas cuando se hace referencia a ella mediante un ShaderEffect.
El valor por defecto es «false».
Esta propiedad se introdujo en QtQuick 2.4.
vertexShader : url
Esta propiedad contiene una referencia a un archivo con el paquete de sombreadores de vértices preprocesado, normalmente con la extensión « .qsb ». El valor se trata como un « URL », de forma similar a otros tipos de QML, como «Image». Debe ser un archivo local o utilizar el esquema «qrc» para acceder a archivos incrustados a través del sistema de recursos de Qt. La URL puede ser absoluta o relativa a la URL del componente.
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.
Véase también fragmentShader.
© 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.



