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 géométriques 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 triés pour minimiser les changements d'état à chaque appel à QSGMaterialShader::updateState().

Le pointeur this et other sont garantis d'avoir le même type().

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

Cette fonction renvoie une nouvelle instance de l'implémentation QSGMaterialShader utilisée pour rendre 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 de renderMode et sera mise en cache en interne.

Pour la plupart des matériaux, l'adresse renderMode peut être ignorée. Quelques 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 prendre en compte les transformations de perspective lorsque le mode de rendu RenderMode3D est utilisé.

QSGMaterial::Flags QSGMaterial::flags() const

Renvoie les drapeaux du matériau.

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

Définit l'indicateur flags sur ce matériau si on est vrai ; sinon, il efface l'attribut.

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

Cette fonction est appelée par le graphe de scène pour demander un identifiant unique à l'instance QSGMaterialShader instanciée par createShader().

Pour de nombreux matériaux, l'approche typique consistera à renvoyer un pointeur vers une instance statique, et donc globalement disponible, de QSGMaterialType. Le site QSGMaterialType est un objet opaque. Son but est uniquement de servir de moyen simple et sûr de générer des identificateurs 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 dans le cas où le matériau est utilisé dans un rendu multivues.

Normalement, la valeur de retour est 1. Un nombre de vues supérieur à 2 implique une passe de rendu multi-vues. Les matériaux qui supportent le multiview sont censés interroger viewCount() dans createShader(), ou dans leur constructeur QSGMaterialShader, et s'assurer que les shaders appropriés sont sélectionnés. Le nuanceur de sommets doit ensuite utiliser gl_ViewIndex pour indexer le tableau de matrices de projection de la vue du modèle, car il y a plusieurs matrices en mode multivue. (une pour chaque vue)

Prenons l'exemple d'un simple nuanceur de vertex :

#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 nuanceur est préparé pour gérer 2 vues, et 2 vues seulement. Il n'est pas compatible avec d'autres nombres de vues. Lors du conditionnement du shader, l'outil qsb doit être invoqué avec --view-count 2 ou, si l'on utilise 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 injectée automatiquement QSHADER_VIEW_COUNT pour simplifier la gestion des différents nombres de vues. Par exemple, s'il est nécessaire de prendre en charge à la fois le non-multiview et le multiview avec un nombre de vues de 2 dans le même fichier source, il est possible de procéder comme suit :

#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 maintenant être exécuté par qsb ou qt_add_shaders() deux fois, une fois sans spécifier le nombre de vues, et une fois avec le nombre de vues fixé à 2. Le matériel peut alors choisir le fichier .qsb approprié en fonction 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 fragment shader)

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
)

Par commodité, il existe également une option MULTIVIEW pour qt_add_shaders(). Cette option exécute d'abord l'outil qsb normalement, puis remplace VIEW_COUNT par 2, fixe GLSL, HLSL, MSL à des valeurs par défaut appropriées, et exécute à nouveau qsb, cette fois en produisant des fichiers .qsb auxquels un suffixe a été ajouté. L'implémentation matérielle peut alors utiliser la surcharge QSGMaterialShader::setShaderFileName() en prenant un argument viewCount, qui choisit automatiquement le bon fichier .qsb.

Ce qui suit est donc en grande partie équivalent à l'exemple d'appel montré ci-dessus, sauf qu'aucun fichier de sortie géré manuellement ne doit être spécifié. Notez qu'il peut y avoir des cas où les versions du langage d'ombrage choisies automatiquement ne sont pas suffisantes, auquel 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
)

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

Cette fonction a été introduite dans Qt 6.8.