Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QRhiTextureRenderTargetDescription Class

Décrit la couleur et la profondeur ou les attachements profondeur/stencil d'une cible de rendu. Plus d'informations...

En-tête : #include <rhi/qrhi.h>
CMake : find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake : QT += gui-private
Depuis : Qt 6.6

Fonctions publiques

QRhiTextureRenderTargetDescription()
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)
const QRhiColorAttachment *cbeginColorAttachments() const
const QRhiColorAttachment *cendColorAttachments() const
const QRhiColorAttachment *colorAttachmentAt(qsizetype index) const
qsizetype colorAttachmentCount() const
(since 6.8) QRhiTexture *depthResolveTexture() const
QRhiRenderBuffer *depthStencilBuffer() const
QRhiTexture *depthTexture() const
void setColorAttachments(std::initializer_list<QRhiColorAttachment> list)
void setColorAttachments(InputIterator first, InputIterator last)
(since 6.8) void setDepthResolveTexture(QRhiTexture *tex)
void setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)
void setDepthTexture(QRhiTexture *texture)
(since 6.9) void setShadingRateMap(QRhiShadingRateMap *map)
(since 6.9) QRhiShadingRateMap *shadingRateMap() const

Description détaillée

Une cible de rendu de texture a zéro ou plusieurs textures comme attachements de couleur, zéro ou un tampon de rendu comme tampon combiné de profondeur/stencil ou zéro ou une texture comme tampon de profondeur.

Remarque : depthStencilBuffer() et depthTexture() ne peuvent pas être tous les deux définis (ils ne peuvent pas être non nuls en même temps).

Examinons quelques exemples d'utilisation en combinaison avec QRhiTextureRenderTarget.

Grâce aux constructeurs, le ciblage d'une texture (sans tampon de profondeur/stencil) est simple :

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture }));

L'exemple suivant crée une cible de rendu de texture qui est configurée pour cibler le niveau mip #2 d'une texture :

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget | QRhiTexture::MipMapped);
texture->create();
QRhiColorAttachment colorAtt(texture);
colorAtt.setLevel(2);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt });

Un autre exemple, cette fois pour effectuer un rendu dans une texture de profondeur :

QRhiTexture *shadowMap = rhi->newTexture(QRhiTexture::D32F, QSize(1024, 1024), 1, QRhiTexture::RenderTarget);
shadowMap->create();
QRhiTextureRenderTargetDescription rtDesc;
rtDesc.setDepthTexture(shadowMap);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

Un cas très courant, ayant une texture comme attachement de couleur et un tampon de rendu comme profondeur/crayon pour permettre le test de profondeur :

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512));
depthStencil->create();
QRhiTextureRenderTargetDescription rtDesc({ texture }, depthStencil);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

Enfin, pour permettre un rendu multi-échantillon de manière portable (donc en supportant également OpenGL ES 3.0), en utilisant un QRhiRenderBuffer comme tampon de couleur (multi-échantillon) et en résolvant ensuite dans une texture 2D régulière (non multi-échantillon). Pour permettre les tests de profondeur, un tampon de profondeur, qui doit également utiliser le même nombre d'échantillons, est également utilisé :

QRhiRenderBuffer *colorBuffer = rhi->newRenderBuffer(QRhiRenderBuffer::Color, QSize(512, 512), 4); // 4x MSAA
colorBuffer->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512), 4);
depthStencil->create();
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiColorAttachment colorAtt(colorBuffer);
colorAtt.setResolveTexture(texture);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt, depthStencil });

Remarque : lorsque la résolution multi-échantillons est activée, les données multi-échantillons peuvent ne pas être écrites du tout. Cela signifie que la texture multi-échantillon dans un attachement de couleur ne doit pas être utilisée par la suite avec des shaders pour l'échantillonnage (ou à d'autres fins) chaque fois qu'une texture résolue est définie, puisque le tampon de couleur multi-échantillon est simplement un stockage intermédiaire qui ne reçoit aucune donnée en retour sur certaines architectures de GPU. Voir PreserveColorContents pour plus de détails.

Remarque : lorsque vous utilisez setDepthTexture(), et non setDepthStencilBuffer(), et que les données de profondeur (stencil) ne sont pas intéressantes par la suite, définissez l'indicateur DoNotStoreDepthStencilContents sur QRhiTextureRenderTarget. Cela permet d'indiquer à l'API 3D sous-jacente que les données de profondeur/stencil peuvent être supprimées, ce qui peut améliorer les performances avec les architectures GPU à mosaïques. Lorsque le tampon profondeur-stencil est un QRhiRenderBuffer (et également pour la texture couleur multi-échantillon, voir la note précédente), cela est implicite, mais avec une profondeur (stencil) QRhiTexture, l'intention doit être déclarée explicitement. Par défaut, QRhi suppose que les données sont intéressantes (par exemple, la texture de profondeur est échantillonnée dans un shader par la suite).

Remarque : il s'agit d'une API RHI avec des garanties de compatibilité limitées, voir QRhi pour plus de détails.

Voir également QRhiColorAttachment et QRhiTextureRenderTarget.

Documentation des fonctions membres

[constexpr noexcept] QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription()

Construit une description vide de la cible de rendu de texture.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)

Construit une description de cible de rendu de texture avec une pièce jointe décrite par colorAttachment.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)

Construit une description de cible de rendu de texture avec deux pièces jointes, une pièce jointe de couleur décrite par colorAttachment, et une pièce jointe de profondeur/stencil avec depthStencilBuffer.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)

Construit une description de cible de rendu de texture avec deux pièces jointes, une pièce jointe de couleur décrite par colorAttachment, et une pièce jointe de profondeur avec depthTexture.

Remarque : depthTexture doit avoir un format approprié, tel que QRhiTexture::D16 ou QRhiTexture::D32F.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cbeginColorAttachments() const

Renvoie un itérateur constant pointant vers le premier élément de la liste des pièces jointes.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cendColorAttachments() const

Renvoie un itérateur constant pointant juste après le dernier élément de la liste des pièces jointes.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::colorAttachmentAt(qsizetype index) const

Renvoie l'attachement de la couleur à l'adresse index spécifiée.

qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount() const

Renvoie le nombre d'attachements de couleur actuellement définis.

[since 6.8] QRhiTexture *QRhiTextureRenderTargetDescription::depthResolveTexture() const

Renvoie la texture à laquelle une texture (ou un tableau de textures) de profondeur multi-échantillon (ou de profondeur-stencil) est résolue. nullptr s'il n'y en a pas, ce qui est le cas le plus courant.

Cette fonction a été introduite dans Qt 6.8.

Voir aussi setDepthResolveTexture(), QRhiColorAttachment::resolveTexture(), et depthTexture().

QRhiRenderBuffer *QRhiTextureRenderTargetDescription::depthStencilBuffer() const

Renvoie le tampon de rendu utilisé comme tampon de profondeur, ou nullptr si aucun tampon n'a été défini.

Voir aussi setDepthStencilBuffer().

QRhiTexture *QRhiTextureRenderTargetDescription::depthTexture() const

Renvoie la texture de profondeur actuellement référencée, ou nullptr si aucune n'a été définie.

Voir également setDepthTexture().

void QRhiTextureRenderTargetDescription::setColorAttachments(std::initializer_list<QRhiColorAttachment> list)

Définit l'adresse list pour les pièces jointes de couleur.

template <typename InputIterator> void QRhiTextureRenderTargetDescription::setColorAttachments(InputIterator first, InputIterator last)

Définit la liste des pièces jointes de couleur via les itérateurs first et last.

[since 6.8] void QRhiTextureRenderTargetDescription::setDepthResolveTexture(QRhiTexture *tex)

Définit la texture de résolution de profondeur (ou de profondeur-stencil) tex.

tex doit être une texture 2D ou un tableau de textures 2D dont le format correspond à la texture définie via setDepthTexture().

Remarque : la résolution des données de profondeur (ou de profondeur-stencil) ne fonctionne que lorsque la fonctionnalité QRhi::ResolveDepthStencil est signalée comme étant prise en charge au moment de l'exécution. La prise en charge de la résolution des données de profondeur n'est pas universellement disponible parmi les API graphiques. Les conceptions qui supposent une disponibilité inconditionnelle de la résolution de la profondeur et du crayon ne sont donc pas portables et doivent être évitées.

Note : En tant que limitation supplémentaire pour OpenGL ES en particulier, l'établissement d'une texture de résolution de profondeur ne peut être fonctionnel qu'en combinaison avec setDepthTexture(), et non avec setDepthStencilBuffer().

Cette fonction a été introduite dans Qt 6.8.

Voir aussi depthResolveTexture(), QRhiColorAttachment::setResolveTexture(), et setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)

Définit l'adresse renderBuffer pour depth-stencil. Il n'est pas obligatoire, par exemple lorsqu'aucun test/écriture de profondeur ou aucune caractéristique liée au pochoir n'est utilisé dans un pipeline graphique dans l'une des passes de rendu pour cette cible de rendu, il peut être laissé à nullptr.

Remarque : depthStencilBuffer() et depthTexture() ne peuvent pas être définis tous les deux (ils ne peuvent pas être non nuls en même temps).

L'utilisation d'un QRhiRenderBuffer sur un QRhiTexture 2D comme tampon de profondeur ou de profondeur/stencil est très courante et constitue l'approche recommandée pour les applications. L'utilisation d'un QRhiTexture, et donc d'un setDepthTexture(), devient pertinente si les données de profondeur sont destinées à être consultées (par exemple, échantillonnées dans un shader) par la suite, ou lorsque multiview rendering est impliqué (parce que la texture de profondeur doit alors être un tableau de textures).

Voir aussi depthStencilBuffer() et setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)

Définit l'adresse texture pour le crayon de profondeur. Il s'agit d'une alternative à setDepthStencilBuffer(), où, au lieu d'un QRhiRenderBuffer, un QRhiTexture d'un type approprié (par exemple, QRhiTexture::D32F) est fourni.

Remarque : depthStencilBuffer() et depthTexture() ne peuvent pas être tous deux définis (ils ne peuvent pas être non nuls en même temps).

texture peut être une texture 2D ou un tableau de textures 2D (lorsque les tableaux de textures sont pris en charge). La spécification d'un tableau de textures est particulièrement importante pour multiview rendering.

Remarque : si texture est un format avec un composant de pochoir, tel que QRhiTexture::D24S8, il servira également de tampon de pochoir.

Voir également depthTexture() et setDepthStencilBuffer().

[since 6.9] void QRhiTextureRenderTargetDescription::setShadingRateMap(QRhiShadingRateMap *map)

S'associe à l'adresse QRhiShadingRateMap map spécifiée. Ceci n'est fonctionnel que lorsque la fonctionnalité QRhi::VariableRateShadingMap est signalée comme étant prise en charge.

Lorsque QRhiCommandBuffer::setShadingRate() est également appelé, le plus élevé des deux taux d'ombrage est utilisé pour chaque tuile. Il n'existe actuellement aucun contrôle sur le comportement du combinateur.

Remarque : lorsque la cible de rendu a déjà été construite (create() a été appelé avec succès), la définition d'une carte de taux d'ombrage implique qu'une nouvelle QRhiRenderPassDescriptor différente est nécessaire et qu'il faut donc la reconstruire. Appelez setRenderPassDescriptor() à nouveau (en dehors d'une passe de rendu) et reconstruisez en appelant create(). Cela a également d'autres conséquences en termes de roulement, par exemple pour les pipelines graphiques : ceux-ci doivent également être associés au nouveau QRhiRenderPassDescriptor et reconstruits. Voir QRhiRenderPassDescriptor::serializedFormat() pour des suggestions sur la façon de gérer cela. N'oubliez pas d'activer le drapeau QRhiGraphicsPipeline::UsesShadingRate.

Cette fonction a été introduite dans Qt 6.9.

Voir aussi shadingRateMap().

[since 6.9] QRhiShadingRateMap *QRhiTextureRenderTargetDescription::shadingRateMap() const

Renvoie l'adresse QRhiShadingRateMap actuellement définie. Par défaut, il s'agit de nullptr.

Cette fonction a été introduite dans Qt 6.9.

Voir aussi setShadingRateMap().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.