QRhiCommandBuffer Class

Documentation des fonctions membres

void QRhiCommandBuffer::beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})

Enregistre le début d'un nouveau cycle de calcul.

resourceUpdates, lorsqu'il n'est pas nul, spécifie un lot de mises à jour de ressources qui doit être validé puis libéré.

flags n'est actuellement pas utilisé.

void QRhiCommandBuffer::beginExternal()

À appeler lorsque l'application en cours s'apprête à mettre en file d'attente des commandes dans le tampon de commandes du passage actuel en appelant directement les fonctions de l'API graphique.

Avec Vulkan, Metal ou Direct3D 12, il est possible d’interroger les objets natifs de tampon de commandes ou d’encodeur via ` nativeHandles()` et d’y mettre des commandes en file d’attente. Avec OpenGL ou Direct3D 11, le contexte (du périphérique) peut être récupéré via ` QRhi::nativeHandles()`. Cependant, cela ne doit jamais être effectué sans s’assurer que l’état de l’ QRhiCommandBuffer reste à jour. D’où la nécessité d’encapsuler tout enregistrement de commande ajouté en externe entre les fonctions `beginExternal()` et ` endExternal()`. Conceptuellement, cela correspond aux fonctions ` beginNativePainting()` et ` endNativePainting()` de l’ QPainter.

Pour OpenGL en particulier, cette fonction a une tâche supplémentaire : elle s'assure que le contexte est rendu actif sur le thread actuel.

Voir également endExternal() et nativeHandles().

void QRhiCommandBuffer::beginPass(QRhiRenderTarget *rt, const QColor &colorClearValue, const QRhiDepthStencilClearValue &depthStencilClearValue, QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})

Enregistre le début d'un nouveau passage de rendu ciblant la cible de rendu rt.

resourceUpdates, lorsqu’elle n’est pas nulle, spécifie un lot de mise à jour de ressources qui doit être validé puis libéré.

Les tampons de couleur et de profondeur/stencil de la cible de rendu sont normalement effacés. Les valeurs d’effacement sont spécifiées dans ` colorClearValue ` et ` depthStencilClearValue`. Il en va autrement lorsque la cible de rendu a été créée avec ` QRhiTextureRenderTarget::PreserveColorContents ` et/ou ` QRhiTextureRenderTarget::PreserveDepthStencilContents`. Dans ce cas, les valeurs d’effacement sont ignorées.

Si ` rt ` est un ` QRhiTextureRenderTarget`, `beginPass()` vérifie si les objets texture et tampon de rendu référencés par la cible de rendu sont à jour. Ce comportement est similaire à celui de la fonction setShaderResources() pour QRhiShaderResourceBindings. Si l’un des éléments associés a été reconstruit depuis l’appel à QRhiTextureRenderTarget::create(), un appel implicite à create() est effectué sur rt. Par conséquent, si rt comporte un élément de couleur associé QRhiTexture texture et qu’il est nécessaire de modifier la taille de la texture, le code suivant est alors valide :

QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ { texture } });
rt->create();
// ...
texture->setPixelSize(new_size);
texture->create();
cb->beginPass(rt, colorClear, dsClear); // this is ok, no explicit rt->create() is required before

flags permet de contrôler certaines fonctionnalités avancées. Un indicateur couramment utilisé est ExternalContents. Celui-ci doit être spécifié chaque fois que beginExternal() sera appelé au cours de la passe lancée par cette fonction.

Voir également endPass() et BeginPassFlags.

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

Enregistre un groupe de débogage nommé dans le tampon de commande avec l'name spécifiée. Ce groupe s'affiche dans les outils de débogage graphique tels que RenderDoc et XCode. La fin du regroupement est indiquée par la fonction debugMarkEnd().

void QRhiCommandBuffer::debugMarkEnd()

Marque la fin d'un groupe de débogage.

void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)

Insère un message de débogage msg dans le flux de commandes.

void QRhiCommandBuffer::dispatch(int x, int y, int z)

Enregistre les éléments de travail de calcul à distribuer, en utilisant les paramètres x, y et z pour spécifier le nombre de groupes de travail locaux dans la dimension correspondante.

void QRhiCommandBuffer::draw(quint32 vertexCount, quint32 instanceCount = 1, quint32 firstVertex = 0, quint32 firstInstance = 0)

Enregistre un tracé non indexé.

Le nombre de sommets est spécifié dans ` vertexCount`. Pour un dessin instancié, définissez ` instanceCount ` sur une valeur différente de 1. ` firstVertex ` correspond à l'index du premier sommet à dessiner. Lors du dessin de plusieurs instances, l'ID de la première instance est spécifié par ` firstInstance`.

void QRhiCommandBuffer::drawIndexed(quint32 indexCount, quint32 instanceCount = 1, quint32 firstIndex = 0, qint32 vertexOffset = 0, quint32 firstInstance = 0)

Enregistre un tirage indexé.

Le nombre de sommets est spécifié dans ` indexCount`. ` firstIndex ` est l'index de base. Le décalage effectif dans le tampon d'index est donné par ` indexOffset + firstIndex * n `, où ` n ` vaut 2 ou 4 selon le type d'élément d'index. ` indexOffset ` est spécifié dans ` setVertexInput()`.

vertexOffset (également appelée « base vertex ») est une valeur signée qui est ajoutée à l’index de l’élément avant l’indexation dans le tampon de sommets. Cette fonctionnalité n’est pas toujours prise en charge, et la valeur est ignorée lorsque la fonctionnalité « QRhi::BaseVertex » est signalée comme non prise en charge.

Pour le dessin instancié, définissez « instanceCount » sur une valeur autre que 1. Lors du dessin de plusieurs instances, l’ID de la première instance est spécifié par « firstInstance ».

[since 6.12] void QRhiCommandBuffer::drawIndexedIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndexedIndirectDrawCommand))

Enregistre un tracé indirect indexé.

Les paramètres de lecture sont fournis par le tampon spécifié dans ` indirectBuffer`, qui doit contenir un tableau d'éléments de type ` QRhiIndexedIndirectDrawCommand`. Les paramètres de ` QRhiIndexedIndirectDrawCommand ` ont la même signification que dans ` drawIndexed()`.

Le décalage, en octets, à partir duquel les paramètres sont lus dans le tampon est spécifié par indirectBufferOffset.

drawCount spécifie le nombre de ces commandes de dessin à émettre.

stride indique la taille en octets de chaque structure de commande de dessin dans le tampon. Cela permet d’intercaler des données personnalisées entre les commandes si nécessaire. La valeur doit être un multiple de 4 et supérieure ou égale à sizeof(QRhiIndexedIndirectDrawCommand).

Cette fonction a été introduite dans Qt 6.12.

[since 6.12] void QRhiCommandBuffer::drawIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndirectDrawCommand))

Enregistre un tracé indirect non indexé.

Les paramètres de lecture sont fournis par le tampon spécifié dans ` indirectBuffer`, qui doit contenir un tableau d’éléments de type ` QRhiIndirectDrawCommand`. Les paramètres de ` QRhiIndirectDrawCommand ` ont la même signification que dans ` draw()`.

Le décalage, en octets, à partir duquel les paramètres sont lus dans le tampon est spécifié par indirectBufferOffset.

drawCount spécifie le nombre de ces commandes de dessin à émettre.

stride indique la taille en octets de chaque structure de commande de dessin dans le tampon. Cela permet d’intercaler des données personnalisées entre les commandes si nécessaire. La valeur doit être un multiple de 4 et supérieure ou égale à sizeof(QRhiIndirectDrawCommand).

Cette fonction a été introduite dans Qt 6.12.

void QRhiCommandBuffer::endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Enregistrements marquant la fin du cycle de calcul en cours.

resourceUpdates, lorsqu'il n'est pas nul, spécifie un lot de mise à jour de ressources qui doit être validé puis libéré.

void QRhiCommandBuffer::endExternal()

À appeler une fois que les commandes ajoutées en externe ont été enregistrées dans le tampon de commandes ou le contexte.

Voir également beginExternal() et nativeHandles().

void QRhiCommandBuffer::endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Enregistrements mettant fin au cycle de rendu en cours.

resourceUpdates, lorsqu'il n'est pas nul, spécifie un lot de mises à jour de ressources qui doit être validé puis libéré.

Voir également beginPass().

double QRhiCommandBuffer::lastCompletedGpuTime()

Renvoie le dernier horodatage disponible, en secondes, lorsque la fonctionnalité « QRhi::EnableTimestamps » était activée lors de la création de l'QRhi. Cette valeur indique le temps écoulé sur le GPU pendant la dernière image traitée.

Il convient de faire preuve de prudence lors de l’interprétation de la valeur, car sa précision et sa granularité ne sont souvent pas contrôlées par Qt et dépendent de l’API graphique sous-jacente et de son implémentation. En particulier, la comparaison des valeurs entre différentes API graphiques et différents matériels est déconseillée et peut s’avérer dénuée de sens.

Les valeurs de temps seront probablement mises à disposition de manière asynchrone. La valeur renvoyée peut donc être 0 (par exemple, pour les 1 à 2 premières images) ou la dernière valeur connue se rapportant à une image précédente. La valeur peut également redevenir 0 dans certaines conditions, par exemple lors du redimensionnement de la fenêtre. On peut s’attendre à ce que la valeur la plus récente disponible soit récupérée dans `beginFrame()` et devienne accessible via cette fonction une fois que `beginFrame()` a renvoyé une valeur.

Faites attention aux conséquences de la modulation de fréquence du GPU et des changements d’horloge du GPU, selon la plateforme. Par exemple, sous Windows, le temps de traitement renvoyé peut varier dans une fourchette assez large d’une image à l’autre avec des cartes graphiques modernes, même en soumettant des images avec une charge de travail similaire, voire identique. D’une manière générale, cela dépasse le champ d’action de Qt et ne relève pas de sa responsabilité. Cependant, le backend D3D12 appelle automatiquement la fonction ID3D12Device::SetStablePowerState() dès que la variable d’environnement QT_D3D_STABLE_POWER_STATE est définie sur une valeur non nulle. Cela peut considérablement stabiliser le résultat. Cela peut également avoir un effet non négligeable sur les temps mesurés côté CPU via QElapsedTimer par exemple, en particulier lorsque des images hors écran sont concernées.

Voir également QRhi::Timestamps et QRhi::EnableTimestamps.

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

Renvoie un pointeur vers une sous-classe de ` QRhiNativeHandles ` spécifique au backend, telle que ` QRhiVulkanCommandBufferNativeHandles`. La valeur renvoyée est ` nullptr ` lorsque l'exposition des ressources natives sous-jacentes n'est pas prise en charge par le backend ou ne s'applique pas à celui-ci.

Voir également QRhiVulkanCommandBufferNativeHandles, QRhiMetalCommandBufferNativeHandles, beginExternal() et endExternal().

[override virtual] QRhiResource::Type QRhiCommandBuffer::resourceType() const

Réimplémente : ` QRhiResource::resourceType()` const.

Renvoie le type de ressource.

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

Il est parfois nécessaire, ou simplement plus pratique, de valider les mises à jour des ressources sans lancer de passe de rendu. L'appel de cette fonction avec ` resourceUpdates ` constitue une alternative au passage de ` resourceUpdates ` à un appel ` beginPass()` (ou ` endPass()`, ce qui serait courant dans le cas de relectures).

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

Enregistrements définissant les constantes de mélange actives sur c.

Cette fonction ne peut être appelée que lorsque le pipeline lié a une valeur définie pour « QRhiGraphicsPipeline::UsesBlendConstants ».

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

Enregistre la configuration d'un nouveau pipeline de calcul ps.

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

Enregistre une nouvelle ps du pipeline graphique.

La définition d’un pipeline graphique ne comportant pas le drapeau UsesScissor désactivera le découpage, avec les API graphiques où cela est applicable, ou définira le rectangle de découpage pour qu’il corresponde à la dernière fenêtre de visualisation définie (avec les API graphiques où le découpage est en réalité toujours actif), afin de garantir un comportement uniforme sur tous les backends QRhi.

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

Enregistre le rectangle « ciseaux » actif spécifié dans scissor.

Cette fonction ne peut être appelée que lorsque le pipeline lié a le drapeau « UsesScissor » activé. Lorsque ce drapeau est activé sur le pipeline actif, cette fonction doit être appelée car le test de recadrage sera activé et un rectangle de recadrage doit donc être fourni.

void QRhiCommandBuffer::setShaderResources(QRhiShaderResourceBindings *srb = nullptr, int dynamicOffsetCount = 0, const QRhiCommandBuffer::DynamicOffset *dynamicOffsets = nullptr)

Enregistrements associant un ensemble de ressources de shader, telles que des tampons uniformes ou des textures, qui sont rendues visibles à un ou plusieurs étages de shader.

srb Peut être nul, auquel cas l’ QRhiShaderResourceBindings associé au pipeline graphique ou de calcul actuel est utilisé. Lorsque srb n’est pas nul, il doit être de type layout-compatible, ce qui signifie que la configuration (nombre de liaisons, type et numéro de liaison de chacune d’entre elles) doit correspondre exactement à l’ QRhiShaderResourceBindings qui était associé au pipeline au moment de l’appel de la fonction create() de ce dernier.

Dans certains cas, un appel à `setShaderResources()` apparemment superflu est obligatoire : lors de la reconstruction d’une ressource référencée depuis ` srb`, par exemple lors d’une modification de la taille d’un ` QRhiBuffer ` suivie d’un appel à ` QRhiBuffer::create()`, c’est à ce moment-là que les objets natifs associés (tels que les ensembles de descripteurs dans le cas de Vulkan) sont mis à jour pour faire référence aux ressources natives actuelles qui sous-tendent les objets QRhiBuffer, QRhiTexture, QRhiSampler référencés depuis srb. Dans ce cas, setShaderResources() doit être appelé même si srb est identique à celui du dernier appel.

Lorsque ` srb ` n’est pas nul, il est garanti que l’objet ` QRhiShaderResourceBindings ` utilisé pour construire le pipeline dans `create()` ne sera en aucun cas accédé. En effet, il n’est même pas nécessaire qu’il soit valide à ce stade : il est tout à fait valable de détruire le `srb` associé au pipeline après `create()` et d’en spécifier explicitement un autre, ` layout compatible `, à chaque appel à `setShaderResources()`.

dynamicOffsets Permet de spécifier des décalages de tampon pour les tampons uniformes qui ont été associés à srb via QRhiShaderResourceBinding::uniformBufferWithDynamicOffset(). Cela diffère de la fourniture du décalage dans l’ srb lui-même : les décalages dynamiques ne nécessitent pas la création d’une nouvelle QRhiShaderResourceBindings pour chaque décalage différent, peuvent éviter l’écriture des descripteurs sous-jacents (avec les backends où cela s’applique), et peuvent donc s’avérer plus efficaces. Chaque élément de ` dynamicOffsets ` est une paire ` binding ` - ` offset `. ` dynamicOffsetCount ` spécifie le nombre d’éléments dans ` dynamicOffsets`.

[since 6.9] void QRhiCommandBuffer::setShadingRate(const QSize &coarsePixelSize)

Définit le taux d'ombrage pour les appels de dessin suivants à coarsePixelSize.

La valeur par défaut est 1x1.

Ne fonctionne que lorsque la fonctionnalité « QRhi::VariableRateShading » est signalée comme prise en charge et que les QRhiGraphicsPipeline s liées au tampon de commande ont été déclarées « QRhiGraphicsPipeline::UsesShadingRate » lors de leur création.

Appelez la fonction ` QRhi::supportedShadingRates()` pour vérifier quels taux d’ombrage sont pris en charge pour un nombre d’échantillons donné.

Lorsque la fonction ` QRhiShadingRateMap ` et cette fonction sont toutes deux utilisées, c’est le taux d’ombrage le plus élevé des deux qui est utilisé pour chaque tuile. Il n’existe actuellement aucun moyen de contrôler le comportement du combinateur.

Cette fonction a été introduite dans Qt 6.9.

void QRhiCommandBuffer::setStencilRef(quint32 refValue)

Enregistrements définissant la valeur de référence active du pochoir sur refValue.

Cette fonction ne peut être appelée que lorsque le pipeline lié a la valeur « QRhiGraphicsPipeline::UsesStencilRef » définie.

void QRhiCommandBuffer::setVertexInput(int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings, QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0, QRhiCommandBuffer::IndexFormat indexFormat = IndexUInt16)

Enregistre les liaisons d'entrée des sommets.

Le tampon d’index utilisé par les commandes drawIndexed() suivantes est spécifié par indexBuf, indexOffset et indexFormat. indexBuf peut être défini sur null lorsque le dessin indexé n’est pas nécessaire.

Les liaisons de tampons de sommets sont regroupées par lots. startBinding spécifie le numéro de la première liaison. La commande enregistrée lie alors chaque tampon de bindings au point de liaison startBinding + i, où i est l’index dans bindings. Chaque élément de bindings spécifie une QRhiBuffer et un décalage.

Les modifications superflues des entrées de sommets et des index au sein d’un même passage sont automatiquement ignorées par la plupart des backends ; les applications n’ont donc pas besoin de recourir à une optimisation excessive pour éviter les appels à cette fonction.

Prenons un exemple simple : un shader de sommet avec deux entrées :

layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;

et supposons que les données soient disponibles au format entrelacé, en utilisant seulement 2 flottants pour la position (soit 5 flottants par sommet : x, y, r, g, b). Un QRhiGraphicsPipeline pour ce shader peut alors être créé en utilisant la disposition d’entrée suivante :

QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
    { 5 * sizeof(float) }
});
inputLayout.setAttributes({
    { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
    { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
});

Il y a ici une liaison de tampon (numéro de liaison 0), à laquelle deux entrées font référence. Lors de l’enregistrement de la passe, une fois le pipeline configuré, les liaisons de sommets peuvent être spécifiées simplement comme suit, en supposant que `vbuf` soit l’ QRhiBuffer contenant toutes les données entrelacées de position et de couleur :

const QRhiCommandBuffer::VertexInput vbufBinding(vbuf, 0);
cb->setVertexInput(0, 1, &vbufBinding);

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

Enregistre le rectangle de la fenêtre d'affichage active spécifié dans viewport.

Avec les backends dont l’API graphique sous-jacente a le « scissoring » toujours activé, cette fonction définit également le « scissor » pour qu’il corresponde à la fenêtre d’affichage chaque fois que l’ QRhiGraphicsPipeline active n’a pas de paramètre « UsesScissor » défini.