ShaderEffect QML Type

Applique des shaders personnalisés à un rectangle. En savoir plus…

• Liste de tous les membres, y compris les membres hérités

Propriétés

• blending : bool
• cullMode : enumeration
• fragmentShader : url
• log : string
• mesh : variant
• status : enumeration
• supportsAtlasTextures : bool (since QtQuick 2.4)
• vertexShader : url

Description détaillée

Le type ShaderEffect applique un shader personnalisé de type « vertex » et « fragment (pixel) » à un rectangle. Il permet d’ajouter des effets tels que l’ombre portée, le flou, la colorisation et l’effet de page cornée à la scène QML.

Shaders

Dans Qt 5, les effets étaient fournis sous forme de code source GLSL (OpenGL Shading Language), souvent intégré sous forme de chaînes de caractères dans le QML. À partir de Qt 5.8, il est également devenu possible de faire référence à des fichiers, qu’ils soient locaux ou présents dans le système de ressources Qt.

Dans Qt 6, le pipeline de rendu ( Qt Quick ) prend également en charge des API graphiques telles que Vulkan, Metal et Direct3D 11. Par conséquent, l’utilisation de chaînes de code source GLSL n’est plus envisageable. Le nouveau pipeline de shaders repose désormais sur la compilation de code GLSL compatible avec Vulkan en SPIR-V, suivie de la collecte d’informations de réflexion et de la traduction vers d’autres langages de shaders, tels que HLSL, le Metal Shading Language et diverses versions de GLSL. Les ressources ainsi obtenues sont regroupées dans un seul paquet, généralement stocké dans des fichiers portant l’extension « .qsb ». Ce processus s’effectue hors ligne ou, au plus tard, lors de la compilation de l’application. Au moment de l’exécution, le graphe de scène et l’abstraction graphique sous-jacente utilisent ces fichiers « .qsb ». Par conséquent, ShaderEffect attend des références de fichiers (locaux ou qrc) dans Qt 6 à la place du code de shader intégré.

Les propriétés ` vertexShader ` et ` fragmentShader ` sont des URL dans Qt 6 et fonctionnent de manière très similaire à ` Image.source`, par exemple. Seuls les schémas ` file ` et ` qrc ` sont toutefois pris en charge par ShaderEffect. Il est également possible d’omettre le schéma ` file `, ce qui permet de spécifier un chemin relatif de manière pratique. Un tel chemin est résolu par rapport à l’emplacement du composant (le fichier ` .qml `).

Entrées et ressources du shader

Il existe deux types d’entrées pour l’ vertexShader: les uniformes et les entrées de sommets.

Les entrées suivantes sont prédéfinies :

• vec4 qt_Vertex à l'emplacement 0 – position des sommets ; le sommet en haut à gauche a pour position (0, 0), celui en bas à droite (width, height).
• vec2 qt_MultiTexCoord0 à l'emplacement 1 : coordonnées de texture ; la coordonnée en haut à gauche est (0, 0), celle en bas à droite (1, 1). Si supportsAtlasTextures est défini sur true, les coordonnées seront alors basées sur la position dans l'atlas.

Les uniformes suivants sont prédéfinis :

• mat4 qt_Matrix — matrice de transformation combinée, produit des matrices allant de l’élément racine à ce ShaderEffect, et d’une projection orthogonale.
• float qt_Opacity – opacité combinée, produit des opacités allant de l’élément racine à ce ShaderEffect.

De plus, toute propriété pouvant être mappée à un type GLSL peut être mise à la disposition des shaders. La liste suivante indique comment les propriétés sont mappées :

• bool, int, qreal → bool, int, float – Si le type dans le shader n’est pas le même que dans QML, la valeur est convertie automatiquement.
• QColor -> vec4 — Lorsque des couleurs sont transmises au shader, elles sont d’abord pré-multipliées. Ainsi, Qt.rgba(0.2, 0.6, 1.0, 0.5) devient vec4(0.1, 0.3, 0.5, 0.5) dans le shader, par exemple.
• QRect, QRectF -> vec4 - Qt.rect(x, y, w, h) devient vec4(x, y, w, h) dans le shader.
• QPoint, QPointF, QSize, QSizeF -> vec2
• QVector3D -> vec3
• QVector4D -> vec4
• QTransform -> mat3
• QMatrix4x4 -> mat4
• QQuaternion -> vec4, la valeur scalaire est w.
• Image -> sampler2D - L'origine se trouve dans le coin supérieur gauche et les valeurs de couleur sont pré-multipliées. La texture est fournie telle quelle, à l'exclusion du mode de remplissage (fillMode) de l'élément Image. Pour inclure le mode de remplissage, utilisez une valeur de type ShaderEffectSource ou Image::layer::enabled.
• ShaderEffectSource -> sampler2D - L'origine se trouve dans le coin supérieur gauche et les valeurs de couleur sont pré-multipliées.

Les échantillonneurs sont toujours déclarés comme des variables uniformes distinctes dans le code du shader. Les shaders sont libres de choisir n’importe quel point de liaison pour celles-ci, à l’exception de ` 0 `, car celui-ci est réservé au bloc `uniform`.

Certains langages de shader et certaines API distinguent les objets « image » et « échantillonneur ». Qt Quick fonctionne toujours avec des objets « image-échantillonneur » combinés dans les shaders, comme le prend en charge SPIR-V. Par conséquent, les shaders fournis pour ShaderEffect doivent toujours utiliser des déclarations d’échantillonneurs de type « layout(binding = 1) uniform sampler2D tex; ». La couche d’abstraction sous-jacente et le pipeline de shaders se chargent de faire fonctionner cela pour toutes les API et tous les langages de shaders pris en charge, de manière transparente pour les applications.

Le backend du graphe de scène QML peut choisir d’allouer les textures dans des atlas de textures. Si une texture allouée dans un atlas est transmise à un ShaderEffect, elle est par défaut copiée depuis l’atlas de textures vers une texture autonome afin que les coordonnées de texture s’étendent de 0 à 1 et que vous obteniez les modes de bouclage attendus. Cependant, cela augmentera l’utilisation de la mémoire. Pour éviter la copie de texture, définissez ` supportsAtlasTextures ` pour les shaders simples en utilisant `qt_MultiTexCoord0`, ou pour chaque « `uniform sampler2D <name>` », déclarez un « `uniform vec4 qt_SubRect_<name>` » auquel sera attribué le rectangle source normalisé de la texture. Pour les textures autonomes, le rectangle source est [0, 1]x[0, 1]. Pour les textures d’un atlas, le rectangle source correspond à la partie de l’atlas de textures où la texture est stockée. La formule correcte pour calculer les coordonnées de texture d’une texture nommée « source » au sein d’un atlas de textures est « qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0 ».

La sortie de l’ fragmentShader doit être prémultipliée. Si l’option « blending » est activée, le mélange « source-over » est utilisé. Cependant, il est possible d’obtenir un mélange additif en renvoyant zéro dans le canal alpha.

import QtQuick 2.0

Rectangle {
    width: 200; height: 100
    Row {
        Image { id: img;
                sourceSize { width: 100; height: 100 } source: "qt-logo.png" }
        ShaderEffect {
            width: 100; height: 100
            property variant src: img
            vertexShader: "myeffect.vert.qsb"
            fragmentShader: "myeffect.frag.qsb"
        }
    }
}

Cet exemple part du principe que les fichiers « myeffect.vert » et « myeffect.frag » contiennent du code GLSL de type Vulkan, traité par l’outil « qsb » afin de générer les fichiers « .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;
}

Utilisation d’un seul shader

Il n’est pas obligatoire de spécifier à la fois vertexShader et fragmentShader. Dans la pratique, de nombreuses implémentations de ShaderEffect ne fourniront qu’un shader de fragment, tout en s’appuyant sur le shader de sommet intégré par défaut.

Le shader de sommets par défaut transmet la coordonnée de texture au shader de fragments sous la forme de ` vec2 qt_TexCoord0 ` à l'emplacement ` 0`.

Le shader de fragment par défaut s'attend à ce que la coordonnée de texture lui soit transmise par le shader de sommet sous la forme d'vec2 qt_TexCoord0 s à l'emplacement 0, et il effectue un échantillonnage à partir d'un sampler2D nommé source au point de liaison 1.

ShaderEffect et couches d’éléments

Le type ShaderEffect peut être combiné avec des couches d'éléments ( layered items).

Couche avec effet désactivé

Couche avec effet activé

Item { id: layerRoot layer.enabled: true layer.effect: ShaderEffect { fragmentShader: "effect.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D source; void main() { vec4 p = texture(source, qt_TexCoord0); float g = dot(p.xyz, vec3(0.344, 0.5, 0.156)); fragColor = vec4(g, g, g, p.a) * qt_Opacity; }

Il est également possible de combiner plusieurs éléments en couches :

Rectangle { id: gradientRect; width: 10 height: 10 gradient: Gradient { GradientStop { position: 0; color: "white" } GradientStop { position: 1; color: "steelblue" } } visible: false; // should not be visible on screen. layer.enabled: true; layer.smooth: true } Text { id: textItem font.pixelSize: 48 text: "Gradient Text" anchors.centerIn: parent layer.enabled: true // This item should be used as the 'mask' layer.samplerName: "maskSource" layer.effect: ShaderEffect { property var colorSource: gradientRect; fragmentShader: "mask.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D colorSource; layout(binding = 2) uniform sampler2D maskSource; void main() { fragColor = texture(colorSource, qt_TexCoord0) * texture(maskSource, qt_TexCoord0).a * qt_Opacity; }

Autres remarques

Par défaut, le ShaderEffect se compose de quatre sommets, un pour chaque coin. Pour les transformations de sommets non linéaires, comme l'effet de page qui se recourbe, vous pouvez définir une grille fine de sommets en spécifiant une résolution d'mesh.

Migration depuis Qt 5

Pour les applications Qt 5 comportant des éléments ShaderEffect, la migration vers Qt 6 implique :

• le déplacement du code de shader vers des fichiers séparés « .vert » et « .frag »,
• la mise à jour des shaders vers un GLSL compatible avec Vulkan,
• l'exécution de l'outil qsb sur ces fichiers,
• l’intégration des fichiers .qsb ainsi générés dans l’exécutable à l’aide du système de ressources Qt,
• et en référençant le fichier dans les propriétés « vertexShader » et « fragmentShader ».

Comme décrit dans le module Qt Shader Tools, certaines de ces étapes peuvent être automatisées en laissant CMake invoquer l’outil qsb au moment de la compilation. Voir qt_add_shaders() pour plus d’informations et d’exemples.

En ce qui concerne la mise à jour du code du shader, vous trouverez ci-dessous un aperçu des modifications couramment requises.

attribute highp vec4 qt_Vertex;
attribute highp vec2 qt_MultiTexCoord0;
varying highp vec2 coord;
uniform highp mat4 qt_Matrix;
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#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;
}

Le processus de conversion consiste principalement à mettre à jour le code pour le rendre compatible avec GL_KHR_vulkan_glsl. Il convient de noter qu’ Qt Quick utilise un sous-ensemble des fonctionnalités fournies par GLSL et Vulkan ; par conséquent, le processus de conversion des shaders ShaderEffect classiques est généralement simple.

• La directive ` version ` doit indiquer ` 440 ` ou ` 450`, bien que la spécification d’une autre version de GLSL puisse également fonctionner, car l’extension `GL_KHR_vulkan_glsl` est conçue pour GLSL 140 et les versions supérieures.
• Les entrées et les sorties doivent utiliser les mots-clés modernes GLSL in et out. De plus, la spécification d’un emplacement est obligatoire. Les espaces de noms des emplacements d’entrée et de sortie sont distincts ; il est donc sans risque d’attribuer des emplacements commençant à 0 pour les deux.
• En ce qui concerne les entrées du shader de sommets, les seules possibilités offertes par ShaderEffect sont l’emplacement 0 pour la position des sommets (traditionnellement appelé qt_Vertex) et l’emplacement 1 pour les coordonnées de texture (traditionnellement appelé qt_MultiTexCoord0).
• Les sorties du shader de sommets et les entrées du shader de fragments sont définies par le code du shader. Le shader de fragments doit disposer d’une sortie « vec4 » à l’emplacement 0 (généralement appelée « fragColor »). Pour une portabilité maximale, les sorties du shader de sommets et les entrées du shader de fragments doivent utiliser à la fois le même numéro d’emplacement et le même nom. Lorsque seul un shader de fragments est spécifié, les coordonnées de texture sont transmises depuis le shader de sommets intégré sous la forme vec2 qt_TexCoord0 à l’emplacement 0, comme le montrent les extraits de code ci-dessus.
• Les variables uniformes en dehors d’un bloc « uniform » ne sont pas autorisées. Les données uniformes doivent plutôt être déclarées dans un bloc « uniform » avec un point de liaison 0.
• Le bloc « uniform » doit utiliser le qualificateur « std140 ».
• Au moment de l’exécution, les shaders de sommets et de fragments recevront le même tampon uniforme lié au point de liaison 0. Par conséquent, en règle générale, les déclarations de blocs uniformes doivent être identiques entre les shaders. Cela inclut également les membres qui ne sont pas utilisés dans l’un des shaders. Les noms des membres doivent correspondre, car avec certaines API graphiques, le bloc « uniform » est converti en une structure « uniform » traditionnelle, de manière transparente pour l’application.
• Lorsque vous ne fournissez qu’un seul des shaders, veillez à ce que les shaders intégrés s’attendent à trouver qt_Matrix et qt_Opacity en tête du bloc d’uniformes (plus précisément, aux décalages 0 et 64, respectivement). En règle générale, incluez-les toujours comme premier et deuxième membres du bloc.
• Dans l’exemple, le bloc `uniform` spécifie le nom de bloc ` buf`. Ce nom peut être modifié librement, mais doit être identique d’un shader à l’autre. L’utilisation d’un nom d’instance, tel que ` layout(...) uniform buf { ... } instance_name; `, est facultative. Lorsqu’il est spécifié, tous les accès aux membres doivent être qualifiés par `instance_name`.

varying highp vec2 coord;
uniform lowp float qt_Opacity;
uniform sampler2D src;
void main() {
    lowp vec4 tex = texture2D(src, coord);
    gl_FragColor = vec4(vec3(dot(tex.rgb,
                        vec3(0.344, 0.5, 0.156))),
                             tex.a) * qt_Opacity;
}

#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;
}

• Les qualificatifs de précision (lowp, mediump, highp) ne sont actuellement pas utilisés.
• L'appel des fonctions GLSL intégrées doit respecter la nomenclature GLSL moderne, notamment en utilisant « texture() » au lieu de « texture2D() ».
• Les échantillonneurs doivent utiliser des points de liaison commençant à 1.
• Lorsque Qt Quick effectue un rendu avec multiview activé, par exemple parce qu’il fait partie d’un rendu de scène 3D dans un environnement VR/AR où le contenu des yeux gauche et droit est généré en un seul passage, les shaders de ShaderEffect doivent être écrits en tenant compte de cela. Avec un nombre de vues égal à 2, par exemple, il y aura des matrices d’ 2 s (qt_Matrix est un tableau de type mat4 comportant deux éléments). Le shader de sommets doit prendre en compte l’ gl_ViewIndex. Consultez la section « Multiview » du manuel QSB pour obtenir des informations générales sur la création de shaders compatibles avec le multivue.

Voir également Item Layers, le manuel QSB et qt_add_shaders.

Documentation sur les propriétés

blending : bool

Si cette propriété est définie sur « true », le résultat de l'fragmentShader est fusionné avec l'arrière-plan à l'aide du mode de fusion « source-over ». Si elle est définie sur « false », l'arrière-plan n'est pas pris en compte. La fusion réduit les performances ; il est donc recommandé de définir cette propriété sur « false » lorsque la fusion n'est pas nécessaire. La valeur par défaut est « true ».

cullMode : enumeration

Cette propriété définit les côtés de l'élément qui doivent être visibles.

La valeur par défaut est NoCulling.

fragmentShader : url

Cette propriété contient une référence à un fichier contenant le paquet de shaders de fragment prétraités, dont l'extension est généralement « .qsb ». La valeur est traitée comme un « URL », à l'instar d'autres types QML, tels que « Image ». Il doit s'agir soit d'un fichier local, soit d'un fichier accessible via le schéma « qrc » pour les fichiers intégrés via le système de ressources Qt. L’URL peut être absolue ou relative à l’URL du composant.

Voir également vertexShader.

log : string [read-only]

Cette propriété contient un journal des avertissements et des erreurs générés lors de la dernière tentative de compilation des shaders. Elle est mise à jour dès que la propriété « status » prend la valeur « Compiled » ou « Error ».

Voir également status.

mesh : variant

Cette propriété définit le maillage utilisé pour dessiner l'ShaderEffect. Elle peut contenir n'importe quel objet de type « GridMesh ». Si une valeur de taille est attribuée à cette propriété, l'ShaderEffect utilise implicitement un « GridMesh » dont la valeur est « mesh resolution ». Par défaut, cette propriété a une taille de 1x1.

Voir également GridMesh.

status : enumeration [read-only]

Cette propriété indique l'état actuel des shaders.

Lors de la définition du code source du shader de fragment ou de sommet, le statut passe à « Non compilé ». La première fois que l’ ShaderEffect e est rendu avec un nouveau code source de shader, les shaders sont compilés et liés, et le statut passe à « Compilé » ou « Erreur ».

Lorsque la compilation à l’exécution n’est pas activée et que les propriétés du shader font référence à des fichiers contenant du bytecode, le statut est toujours « Compilé ». Le contenu du shader n’est pas examiné (à l’exception d’une réflexion de base visant à découvrir les éléments d’entrée de sommet et les données du tampon constant) avant une étape ultérieure du pipeline de rendu ; les erreurs potentielles (telles que les incompatibilités de disposition ou de signature racine) ne seront donc détectées qu’à un stade ultérieur.

Voir également log.

supportsAtlasTextures : bool [since QtQuick 2.4]

Définissez cette propriété sur « true » pour confirmer que votre code de shader ne repose pas sur le fait que qt_MultiTexCoord0 varie de (0,0) à (1,1) par rapport au maillage. Dans ce cas, la plage de qt_MultiTexCoord0 dépendra plutôt de la position de la texture au sein de l’atlas. Cette propriété n’a actuellement aucun effet s’il y a moins ou plus d’un uniforme d’échantillonneur utilisé en entrée de votre shader.

Cela diffère de la fourniture d’uniformes qt_SubRect_<nom> en ce sens que ces derniers permettent de dessiner une ou plusieurs textures de l’atlas dans un seul élément « ShaderEffect », tandis que «supportsAtlasTextures» permet de regrouper en un seul dessin plusieurs instances d’un composant « ShaderEffect » utilisant chacune une image source différente de l’atlas. Ces deux méthodes empêchent qu’une texture soit copiée hors de l’atlas lorsqu’elle est référencée par un ShaderEffect.

La valeur par défaut est « false ».

Cette propriété a été introduite dans QtQuick 2.4.

vertexShader : url

Cette propriété contient une référence à un fichier contenant le paquet de shaders de sommets prétraité, généralement avec l'extension « .qsb ». La valeur est traitée comme un « URL », à l'instar d'autres types QML, tels que « Image ». Il doit s'agir soit d'un fichier local, soit d'un fichier accessible via le schéma « qrc » pour les fichiers intégrés via le système de ressources Qt. L’URL peut être absolue ou relative à l’URL du composant.

Voir également fragmentShader.