QRhiCommandBuffer Class

Documentation des fonctions membres

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

Enregistrements démarrant une nouvelle passe de calcul.

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

flags n'est pas utilisé actuellement.

void QRhiCommandBuffer::beginExternal()

À appeler lorsque l'application avant l'application est sur le point de mettre en file d'attente des commandes dans le tampon de commande de la passe actuelle en appelant directement les fonctions de l'API graphique.

Avec Vulkan, Metal ou Direct3D 12, il est possible d'interroger le tampon de commande natif ou les objets d'encodage via nativeHandles() et de leur envoyer des commandes enqueue. Avec OpenGL ou Direct3D 11, le contexte (du périphérique) peut être récupéré à partir de QRhi::nativeHandles(). Cependant, cela ne doit jamais être fait sans s'assurer que l'état de QRhiCommandBuffer's reste à jour. D'où la nécessité d'envelopper tout enregistrement de commande ajouté de l'extérieur entre beginExternal() et endExternal(). D'un point de vue conceptuel, il s'agit de la même chose que les fonctions beginNativePainting() et endNativePainting() de QPainter.

Pour OpenGL en particulier, cette fonction a une tâche supplémentaire : elle s'assure que le contexte est mis à jour sur le thread courant.

Voir également endExternal() et nativeHandles().

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

Enregistrements démarrant une nouvelle passe de rendu ciblant la cible de rendu rt.

resourceUpdatessi elle n'est pas nulle, spécifie un lot de mise à jour de ressources qui doit être engagé 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 existe une exception lorsque la cible de rendu a été créée avec QRhiTextureRenderTarget::PreserveColorContents et/ou QRhiTextureRenderTarget::PreserveDepthStencilContents. Les valeurs d'effacement sont alors ignorées.

Si rt est un QRhiTextureRenderTarget, beginPass() vérifie que les objets texture et renderbuffer référencés par la cible de rendu sont à jour. Ceci est similaire à ce que fait setShaderResources() pour QRhiShaderResourceBindings. Si l'une des pièces jointes a été reconstruite depuis QRhiTextureRenderTarget::create(), un appel implicite à create() est effectué sur rt. Par conséquent, si rt a une pièce jointe de couleur QRhiTexture texture , et que l'on a besoin de donner une taille différente à la texture, la procédure suivante est alors valable :

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 permettent de contrôler certaines fonctionnalités avancées. Un drapeau couramment utilisé est ExternalContents. Il doit être spécifié chaque fois que beginExternal() sera appelé dans la passe lancée par cette fonction.

Voir aussi endPass() et BeginPassFlags.

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

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

void QRhiCommandBuffer::debugMarkEnd()

Enregistre 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)

Enregistrements distribuant des éléments de travail de calcul, avec x, y, et z spécifiant 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 dessin non indexé.

Le nombre de sommets est spécifié dans vertexCount. Pour un dessin instancié, définissez instanceCount à une valeur différente de 1. firstVertex est l'index du premier sommet à dessiner. Lorsque plusieurs instances sont dessinées, le premier identifiant d'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 dessin indexé.

Le nombre de sommets est spécifié dans indexCount. firstIndex est l'indice de base. Le décalage effectif dans le tampon d'index est donné par indexOffset + firstIndex * n où n est 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 valeur n'est pas toujours prise en charge et est ignorée lorsque la fonctionnalité QRhi::BaseVertex est signalée comme non prise en charge.

Pour le dessin d'instances, définissez instanceCount à une valeur autre que 1. Lorsque vous dessinez plusieurs instances, le premier identifiant d'instance est spécifié par firstInstance.

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

Enregistrements terminant la passe de calcul en cours.

resourceUpdatesSi elle n'est pas nulle, spécifie un lot de mise à jour de ressources qui doit être validé et ensuite libéré.

void QRhiCommandBuffer::endExternal()

À appeler une fois que les commandes ajoutées de l'extérieur sont enregistrées dans le tampon de commande ou le contexte.

Voir aussi beginExternal() et nativeHandles().

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

Enregistrements terminant la passe de rendu en cours.

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

Voir aussi beginPass().

double QRhiCommandBuffer::lastCompletedGpuTime()

Renvoie le dernier horodatage disponible, en secondes, lorsque QRhi::EnableTimestamps a été activé lors de la création de QRhi. La valeur indique le temps écoulé sur le GPU lors de la dernière image terminée.

Il faut faire attention à 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 être dénuée de sens.

Lorsque l'image a été enregistrée avec beginFrame() et endFrame(), c'est-à-dire avec une chaîne d'échange, les valeurs de synchronisation seront probablement disponibles 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 référant à une image précédente. La valeur peut également redevenir 0 dans certaines conditions, par exemple en cas de redimensionnement de la fenêtre. On peut s'attendre à ce que la valeur disponible la plus récente soit récupérée dans beginFrame() et devienne interrogeable via cette fonction une fois que beginFrame() est retournée.

D'autre part, avec les images hors écran, la valeur renvoyée est à jour une fois que endOffscreenFrame() est renvoyé, parce que les images hors écran réduisent le pipelining du GPU et attendent que les commandes soient terminées.

Attention aux conséquences de la mise à l'échelle de la fréquence du GPU et des changements d'horloge du GPU, en fonction de la plateforme. Par exemple, sous Windows, la durée renvoyée peut varier dans une fourchette assez large entre les images avec des cartes graphiques modernes, même si l'on soumet des images avec une charge de travail similaire ou identique. Qt n'est pas en mesure de contrôler et de résoudre ce problème, d'une manière générale. Cependant, le backend D3D12 appelle automatiquement ID3D12Device::SetStablePowerState() chaque fois que la variable d'environnement QT_D3D_STABLE_POWER_STATE est réglée sur une valeur non nulle. Cela peut grandement stabiliser le résultat. Cela peut également avoir un effet non significatif sur les temps mesurés côté CPU via QElapsedTimer par exemple, en particulier lorsque des images hors écran sont impliquées.

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

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

Renvoie un pointeur vers une sous-classe 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 n'est pas applicable à celui-ci.

Voir aussi 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 d'effectuer des mises à jour de ressources sans lancer une passe de rendu. L'appel à cette fonction avec resourceUpdates est une alternative à la transmission de resourceUpdates à un appel à beginPass() (ou endPass(), ce qui serait typique dans le cas de retours en arrière).

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

Enregistre le réglage des constantes de mélange actives sur c.

Cette fonction ne peut être appelée que lorsque le pipeline lié a été défini sur QRhiGraphicsPipeline::UsesBlendConstants.

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

Enregistre la mise en place d'un nouveau pipeline de calcul ps.

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

Enregistre la configuration d'un nouveau pipeline graphique ps.

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

Enregistre la définition du rectangle de ciseaux actif spécifié à l'adresse scissor.

Cette fonction ne peut être appelée que lorsque la canalisation liée a été définie à l'adresse UsesScissor. Lorsque le drapeau est activé sur le pipeline actif, cette fonction doit être appelée parce que les tests de ciseaux seront activés et qu'un rectangle de ciseaux doit être fourni.

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

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

srb peut être nul, auquel cas le pipeline graphique ou de calcul associé à QRhiShaderResourceBindings est utilisé. Lorsque srb n'est pas nul, il doit s'agir de layout-compatible, ce qui signifie que la disposition (nombre de liaisons, type et numéro de liaison de chaque liaison) doit correspondre entièrement à QRhiShaderResourceBindings qui était associé au pipeline au moment de l'appel à la fonction create() du pipeline.

Dans certains cas, l'appel à setShaderResources(), apparemment inutile, est obligatoire : lors de la reconstruction d'une ressource référencée à partir de srb, par exemple en modifiant la taille d'un QRhiBuffer suivi d'un QRhiBuffer::create(), c'est l'endroit où 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 soutiennent les objets QRhiBuffer, QRhiTexture, QRhiSampler référencés à partir de srb. Dans ce cas, setShaderResources() doit être appelé même si srb est le même que lors du dernier appel.

Lorsque srb n'est pas nul, l'objet QRhiShaderResourceBindings avec lequel le pipeline a été construit dans create() est garanti de ne pas être accédé sous quelque forme que ce soit. En fait, il n'a pas besoin d'être valide même à ce stade : détruire le srb associé au pipeline après create() et à la place en spécifier explicitement un autre, layout compatible dans chaque appel à setShaderResources() est valide.

dynamicOffsets permet de spécifier les décalages de tampons pour les tampons uniformes qui ont été associés à srb via QRhiShaderResourceBinding::uniformBufferWithDynamicOffset(). C'est différent de fournir le décalage dans srb lui-même : les décalages dynamiques ne nécessitent pas la construction d'un nouveau QRhiShaderResourceBindings pour chaque décalage différent, peuvent éviter d'écrire les descripteurs sous-jacents (avec les backends le cas échéant), et donc ils peuvent être 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.

Fonctionnel uniquement lorsque la fonctionnalité QRhi::VariableRateShading est signalée comme étant prise en charge et que le(s) QRhiGraphicsPipeline(s) lié(s) au tampon de commande déclarait(ent) QRhiGraphicsPipeline::UsesShadingRate lors de sa(leur) création.

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

Lorsqu'une fonction QRhiShadingRateMap et cette fonction sont toutes deux utilisées, le taux d'ombrage le plus élevé des deux est utilisé pour chaque tuile. Il n'existe actuellement aucun contrôle sur le comportement du combinateur.

Cette fonction a été introduite dans Qt 6.9.

void QRhiCommandBuffer::setStencilRef(quint32 refValue)

Enregistrements fixant la valeur de référence du pochoir actif à refValue.

Cette fonction ne peut être appelée que lorsque le pipeline lié a été défini à QRhiGraphicsPipeline::UsesStencilRef.

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 vertex.

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

Les liaisons de tampons de sommets sont groupées. startBinding spécifie le premier numéro de liaison. La commande enregistrée lie ensuite chaque tampon à partir de bindings au point de liaison startBinding + i où i est l'index dans bindings. Chaque élément de bindings spécifie un QRhiBuffer et un décalage.

Les entrées de sommets superflues et les changements d'index dans la même passe sont automatiquement ignorés par la plupart des backends et les applications n'ont donc pas besoin de sur-optimiser pour éviter les appels à cette fonction.

Prenons un exemple simple : un vertex shader avec deux entrées :

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

et supposons que nous disposons des données dans un format entrelacé, en utilisant seulement 2 flottants pour la position (donc 5 flottants par vertex : x, y, r, g, b). Un QRhiGraphicsPipeline pour ce shader peut alors être créé en utilisant le layout d'entrée :

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

Ici, il y a une liaison de tampon (liaison numéro 0), avec deux entrées qui y font référence. Lors de l'enregistrement de la passe, une fois que le pipeline est défini, les fixations de vertex peuvent être spécifiées simplement comme suit, en supposant que vbuf est le QRhiBuffer avec toutes les données de position+couleur entrelacées :

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

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

Enregistrements définissant le rectangle de la fenêtre active spécifié dans viewport.

Avec les backends où l'API graphique sous-jacente a toujours activé le scissoring, cette fonction définit également le scissor pour qu'il corresponde au viewport lorsque le QRhiGraphicsPipeline actif n'a pas UsesScissor de défini.