QSGMaterial Class

Documentation des fonctions membres

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

Compare ce matériau à other et renvoie 0 s’ils sont égaux ; -1 si ce matériau doit être classé avant other et 1 si other doit être classé avant.

Le graphe de scène peut réorganiser les nœuds de géométrie afin de minimiser les changements d’état. La fonction de comparaison est appelée pendant le processus de tri afin que les matériaux puissent être classés de manière à minimiser les changements d’état à chaque appel à QSGMaterialShader::updateState().

Il est garanti que le pointeur « this » et « other » ont la même valeur de type().

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

Cette fonction renvoie une nouvelle instance de l'implémentation de ` QSGMaterialShader ` utilisée pour le rendu de la géométrie pour une implémentation spécifique de ` QSGMaterial`.

La fonction ne sera appelée qu’une seule fois pour chaque combinaison de type de matériau et d’ renderMode, et sera mise en cache en interne.

Pour la plupart des matériaux, l’ renderMode peut être ignorée. Certains matériaux peuvent nécessiter un traitement personnalisé pour des modes de rendu spécifiques. Par exemple, si le matériau implémente l’anticrénelage d’une manière qui doit tenir compte des transformations de perspective lorsque RenderMode3D est utilisé.

QSGMaterial::Flags QSGMaterial::flags() const

Renvoie les indicateurs du matériau.

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

Définit les indicateurs « flags » sur ce matériau si la valeur de « on » est vraie ; dans le cas contraire, efface cet attribut.

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

Cette fonction est appelée par le graphe de scène pour récupérer l'identifiant unique de l'instance de ` QSGMaterialShader ` créée par la fonction ` createShader()`.

Pour de nombreux matériaux, l'approche courante consistera à renvoyer un pointeur vers une instance statique — et donc accessible globalement — d'QSGMaterialType. L'objet QSGMaterialType est un objet opaque. Son seul but est de fournir un moyen simple et sans risque de type pour générer des identifiants de matériaux uniques.

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

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

Renvoie le nombre de vues lorsque le matériau est utilisé dans un rendu multi-vues.

Normalement, la valeur renvoyée est 1. Un nombre de vues supérieur à 2 implique un passage de rendu multi-vues. Les matériaux prenant en charge le mode multivue doivent interroger la fonction `viewCount()` dans ` createShader()` ou dans leur constructeur ` QSGMaterialShader `, et s’assurer que les shaders appropriés sont sélectionnés. Le shader de sommets doit ensuite utiliser ` gl_ViewIndex ` pour indexer le tableau de matrices de projection modèle-vue, car il existe plusieurs matrices en mode multivue (une pour chaque vue).

Prenons, à titre d’exemple, le shader de sommets simple suivant :

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

Ce shader est conçu pour gérer 2 vues, et 2 vues uniquement. Il n’est pas compatible avec d’autres nombres de vues. Lors de la configuration du shader, l’outil qsb doit être appelé avec l’option --view-count 2 ou, si vous utilisez l’intégration CMake, VIEW_COUNT 2 doit être spécifié dans la commande qt_add_shaders().

Les développeurs sont encouragés à utiliser la variable de préprocesseur QSHADER_VIEW_COUNT, injectée automatiquement, afin de simplifier la gestion des différents nombres de vues. Par exemple, s’il est nécessaire de prendre en charge à la fois le mode sans vue multiple et le mode avec vue multiple (nombre de vues égal à 2) dans le même fichier source, la procédure suivante peut être suivie :

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

Le même fichier source peut désormais être traité deux fois via ` qsb ` ou ` qt_add_shaders() ` : une fois sans spécifier le nombre de vues, et une fois avec le nombre de vues défini sur 2. Le matériel peut alors choisir le fichier .qsb approprié en fonction de la valeur de `viewCount()` au moment de l’exécution.

Avec CMake, cela pourrait ressembler à ce qui suit. Dans cet exemple, le fichier « QSGMaterialShader » correspondant est censé choisir entre :/shaders/example.vert.qsb et :/shaders/multiview/example.vert.qsb en fonction de la valeur de viewCount(). (Il en va de même pour le shader de fragment.)

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
)

Pour plus de commodité, il existe également une option ` MULTIVIEW ` pour `qt_add_shaders()`. Celle-ci exécute d’abord l’outil ` qsb ` normalement, puis remplace ` VIEW_COUNT ` par ` 2`, définit ` GLSL`, ` HLSL` et ` MSL ` sur des valeurs par défaut appropriées, et relance ` qsb `, générant cette fois-ci des fichiers `.qsb` avec un suffixe ajouté. L’implémentation du matériau peut alors utiliser la surcharge de la fonction ` QSGMaterialShader::setShaderFileName()` prenant un argument de type ` viewCount `, qui sélectionne automatiquement le fichier .qsb approprié.

Ce qui suit est donc globalement équivalent à l’exemple d’appel présenté ci-dessus, à la différence qu’il n’est pas nécessaire de spécifier manuellement des fichiers de sortie. Notez qu’il peut arriver que les versions du langage de shading choisies automatiquement ne soient pas suffisantes ; dans ce cas, les applications doivent continuer à tout spécifier explicitement.

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

Consultez QRhi::MultiView, QRhiColorAttachment::setMultiViewCount() et QRhiGraphicsPipeline::setMultiViewCount() pour plus de détails de bas niveau sur la prise en charge multivue dans Qt. Le moteur de rendu de graphe de scène Qt Quick est prêt à reconnaître les cibles de rendu multivue, lorsqu’elles sont spécifiées via QQuickRenderTarget::fromRhiRenderTarget() ou les fonctions spécifiques à l’API 3D, telles que fromVulkanImage() avec un argument arraySize supérieur à 1. Le moteur de rendu transmettra alors le nombre de vues aux pipelines graphiques et aux matériaux.

Cette fonction a été introduite dans Qt 6.8.