QRhiColorAttachment Class
Décrit l'attachement d'une couleur unique à 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
| QRhiColorAttachment() | |
| QRhiColorAttachment(QRhiRenderBuffer *renderBuffer) | |
| QRhiColorAttachment(QRhiTexture *texture) | |
| int | layer() const |
| int | level() const |
(since 6.7) int | multiViewCount() const |
| QRhiRenderBuffer * | renderBuffer() const |
| int | resolveLayer() const |
| int | resolveLevel() const |
| QRhiTexture * | resolveTexture() const |
| void | setLayer(int layer) |
| void | setLevel(int level) |
(since 6.7) void | setMultiViewCount(int count) |
| void | setRenderBuffer(QRhiRenderBuffer *rb) |
| void | setResolveLayer(int layer) |
| void | setResolveLevel(int level) |
| void | setResolveTexture(QRhiTexture *tex) |
| void | setTexture(QRhiTexture *tex) |
| QRhiTexture * | texture() const |
Description détaillée
Un attachement de couleur est soit un QRhiTexture, soit un QRhiRenderBuffer. Le premier, c'est-à-dire lorsque texture() est défini, est utilisé dans la plupart des cas. QRhiColorAttachment est généralement utilisé en combinaison avec QRhiTextureRenderTargetDescription.
Remarque : texture() et renderBuffer() ne peuvent pas être définis tous les deux (être non nuls en même temps).
L'utilisation de renderBuffer n'est recommandée que lorsque le multi-échantillonnage est nécessaire. En pratique, il est préférable de s'appuyer sur QRhi::MultisampleRenderBuffer plutôt que sur QRhi::MultisampleTexture, car le premier est disponible dans un plus grand nombre de configurations d'exécution (par exemple, lors de l'exécution d'OpenGL ES 3.0, qui ne prend pas en charge les textures multi-échantillonnées, mais qui prend en charge les tampons de rendu multi-échantillonnés).
Lorsqu'il s'agit d'une texture non multi-échantillonnée, les commandes layer() et level() indiquent la couche ciblée (indice de face 0-5 pour les cubemaps) et le niveau de mip. Pour les textures 3D, layer() indique la tranche (une image 2D dans la texture 3D) sur laquelle le rendu doit être effectué. Pour les tableaux de textures, layer() est l'index du tableau.
Lorsque texture() ou renderBuffer() est un multi-échantillon, resolveTexture() peut être défini de manière facultative. Lorsque cette option est activée, les échantillons sont automatiquement résolus dans cette texture (non multi-échantillonnée) à la fin de la passe de rendu. Lors du rendu dans un tampon de rendu multi-échantillon, c'est la seule façon d'obtenir un contenu résolu et non multi-échantillon. Les textures multi-échantillons permettent l'échantillonnage dans les shaders, il s'agit donc d'une option parmi d'autres.
Remarque : lorsque la résolution est activée, les données multi-échantillons peuvent ne pas être écrites du tout. Cela signifie que le multisample texture() ne doit pas être utilisé par la suite avec les shaders pour l'échantillonnage lorsque resolveTexture() est activé.
Remarque : il s'agit d'une API RHI avec des garanties de compatibilité limitées, voir QRhi pour plus de détails.
Voir également QRhiTextureRenderTargetDescription.
Documentation des fonctions membres
[constexpr noexcept] QRhiColorAttachment::QRhiColorAttachment()
Construit une description vide de l'attachement de couleur.
QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer)
Construit une description d'attachement de couleur qui spécifie renderBuffer comme tampon de couleur associé.
QRhiColorAttachment::QRhiColorAttachment(QRhiTexture *texture)
Construit une description d'attachement de couleur qui spécifie texture comme tampon de couleur associé.
int QRhiColorAttachment::layer() const
Renvoie l'index de la couche (face cubemap ou couche tableau). 0 par défaut.
Voir aussi setLayer().
int QRhiColorAttachment::level() const
Renvoie le niveau du mip. 0 par défaut.
Voir aussi setLevel().
[since 6.7] int QRhiColorAttachment::multiViewCount() const
Renvoie le nombre de vues actuellement défini. La valeur par défaut est 0, ce qui indique que la cible de rendu avec cet attachement de couleur ne sera pas utilisée avec le rendu multivues.
Cette fonction a été introduite dans Qt 6.7.
Voir aussi setMultiViewCount().
QRhiRenderBuffer *QRhiColorAttachment::renderBuffer() const
Renvoie le tampon de rendu auquel la description de la pièce jointe fait référence, ou nullptr s'il n'y en a pas.
Dans la pratique, l'association d'un QRhiRenderBuffer à un QRhiColorAttachment est la plus judicieuse lors de la mise en place d'un rendu multi-échantillon via un tampon de rendu multi-échantillon color qui est ensuite résolu en une texture non multi-échantillon à la fin de la passe de rendu.
Voir aussi setRenderBuffer().
int QRhiColorAttachment::resolveLayer() const
Renvoie la couche de texture résolue actuellement définie. La valeur par défaut est 0.
Voir aussi setResolveLayer().
int QRhiColorAttachment::resolveLevel() const
Renvoie le niveau de mip de la texture de résolution actuellement défini. La valeur par défaut est 0.
Voir aussi setResolveLevel().
QRhiTexture *QRhiColorAttachment::resolveTexture() const
Renvoie la texture de résolution à laquelle la description de la pièce jointe fait référence, ou nullptr s'il n'y en a pas.
La définition d'une texture de résolution non nulle est applicable lorsque la pièce jointe fait référence à une texture multi-échantillon ou à un tampon de rendu. L'adresse QRhiTexture dans resolveTexture() est alors une texture 2D non multi-échantillonnée (ou un tableau de textures) de la même taille (mais avec un nombre d'échantillons de 1). Le contenu multi-échantillon est automatiquement résolu dans cette texture à la fin de chaque passe de rendu.
Voir aussi setResolveTexture().
void QRhiColorAttachment::setLayer(int layer)
Définit l'indice layer.
Voir aussi layer().
void QRhiColorAttachment::setLevel(int level)
Définit le mip level.
Voir aussi level().
[since 6.7] void QRhiColorAttachment::setMultiViewCount(int count)
Définit la vue count. Une valeur supérieure à 1 indique que la cible de rendu avec cet attachement de couleur sera utilisée avec un rendu multi-vues. La valeur par défaut est 0. Les valeurs inférieures à 2 indiquent qu'il n'y a pas de rendu multi-vues.
Lorsque count est défini sur 2 ou plus, l'attachement de couleur doit être associé à un tableau de texture 2D. layer() et multiViewCount() définissent ensemble la plage d'éléments du tableau de textures qui sont ciblés lors du rendu multivues.
Par exemple, si layer est 0 et multiViewCount est 2, le tableau de textures doit comporter 2 éléments (ou plus) et le rendu multivues ciblera les éléments 0 et 1. La variable gl_ViewIndex dans les nuanceurs a alors une valeur de 0 ou 1, où la vue 0 correspond à l'élément du tableau de textures 0, et la vue 1 à l'élément du tableau 1.
Remarque : le fait de définir une valeur count supérieure à 1, d'utiliser un tableau de textures comme texture() et d'appeler beginPass() sur un QRhiTextureRenderTarget avec cet attachement de couleur implique un rendu multivue pour l'ensemble de la passe de rendu. multiViewCount() ne doit pas être défini si le rendu multivue n'est pas souhaité. Multiview ne peut pas être utilisé avec des types de textures autres que les tableaux de textures 2D. (bien que les textures 3D puissent fonctionner, en fonction de l'API graphique et du backend ; il est néanmoins conseillé aux applications de ne pas s'y fier et de n'utiliser que des tableaux de textures 2D comme cibles de rendu pour le rendu multivue).
Voir GL_OVR_multiview pour plus de détails sur le rendu multiview. Notez que QtGL nécessite également GL_OVR_multiview2 lorsqu'il fonctionne avec OpenGL (ES).
Le rendu multi-vues n'est disponible que lorsque la fonctionnalité MultiView est signalée comme étant prise en charge par isFeatureSupported().
Remarque : pour des raisons de portabilité, il convient d'être conscient des limitations qui existent pour le rendu multi-vues avec certaines API graphiques. Il est recommandé que les passes de rendu multivues ne s'appuient sur aucune des fonctionnalités que GL_OVR_multiview déclare comme n'étant pas prises en charge. La seule exception concerne les sorties d'étages de shaders autres que gl_Position qui dépendent de gl_ViewIndex: on peut s'y fier (même avec OpenGL) car QRhi ne signale jamais que le multiview est pris en charge sans que GL_OVR_multiview2 soit également présent.
Note : Le rendu multivue n'est pas supporté en combinaison avec la tessellation ou les shaders géométriques, même si certaines implémentations de certaines API graphiques peuvent le permettre.
Cette fonction a été introduite dans Qt 6.7.
Voir aussi multiViewCount().
void QRhiColorAttachment::setRenderBuffer(QRhiRenderBuffer *rb)
Définit le tampon de rendu rb.
Remarque : texture() et renderBuffer() ne peuvent pas être tous les deux définis (être non nuls en même temps).
Voir aussi renderBuffer().
void QRhiColorAttachment::setResolveLayer(int layer)
Définit la texture de résolution layer à utiliser.
Voir aussi resolveLayer().
void QRhiColorAttachment::setResolveLevel(int level)
Définit la texture de résolution mip level à utiliser.
Voir également resolveLevel().
void QRhiColorAttachment::setResolveTexture(QRhiTexture *tex)
Définit la texture de résolution tex.
tex est censée être une texture 2D ou un tableau de textures 2D. Dans les deux cas, la résolution cible un seul niveau de mip d'une seule couche (élément de tableau) de tex. Le niveau de mip et la couche de tableau sont spécifiés par resolveLevel() et resolveLayer().
multiview constitue une exception : lorsque l'attachement de couleur est associé à un tableau de textures et que l'option multiview est activée, la texture résolue doit également être un tableau de textures comportant suffisamment d'éléments pour toutes les vues. Dans ce cas, tous les éléments correspondant à des vues sont résolus automatiquement ; le comportement est similaire au pseudo-code suivant :
for (i = 0; i < multiViewCount(); ++i)
resolve texture's layer() + i into resolveTexture's resolveLayer() + iDéfinir une texture non multi-échantillonnée pour résoudre une texture multi-échantillonnée ou un tampon de rendu automatiquement à la fin de la passe de rendu est souvent préférable au fait de travailler avec des textures multi-échantillonnées (et de ne pas définir de texture de résolution), car cela évite d'avoir à écrire des shaders de fragment dédiés qui fonctionnent exclusivement avec des textures multi-échantillonnées (sampler2DMS, texelFetch, etc.), et permet plutôt d'utiliser le même shader que si la texture de l'élément joint n'était pas multi-échantillonnée au départ. Cela se fait au détriment d'une ressource supplémentaire (la texture non multi-échantillonnée tex).
Voir également resolveTexture().
void QRhiColorAttachment::setTexture(QRhiTexture *tex)
Définit la texture tex.
Remarque : texture() et renderBuffer() ne peuvent pas être tous les deux définis (être non nuls en même temps).
Voir aussi texture().
QRhiTexture *QRhiColorAttachment::texture() const
Renvoie la texture à laquelle la description de la pièce jointe fait référence, ou nullptr s'il n'y en a pas.
Voir aussi setTexture().
© 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.
