QRhiColorAttachment Class
Décrit l'application d'une seule couleur à une cible de rendu. En savoir plus...
| 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 couramment utilisé en combinaison avec ` QRhiTextureRenderTargetDescription`.
Remarque : texture() et renderBuffer() ne peuvent pas être tous deux définis (être non nuls en même temps).
Il est recommandé de définir renderBuffer uniquement lorsque le multisampling est nécessaire. Dans la pratique, il est préférable de s’appuyer sur QRhi::MultisampleRenderBuffer plutôt que sur QRhi::MultisampleTexture, car le premier est disponible dans davantage de configurations d’exécution (par exemple lors de l’exécution sous OpenGL ES 3.0, qui ne prend pas en charge les textures multisample, mais prend en charge les buffers de rendu multisample).
Lorsqu’on cible une texture non multi-échantillonnée, les fonctions ` layer()` et ` level()` indiquent la couche ciblée (index de face ` 0-5 ` pour les cubemaps) et le niveau de mip. Pour les textures 3D, ` layer()` spécifie la tranche (une image 2D au sein de la texture 3D) à rendre. Pour les tableaux de textures, ` layer()` correspond à l’index du tableau.
Lorsque texture() ou renderBuffer() est en mode multisample, resolveTexture() peut être défini de manière facultative. Lorsqu’il est défini, les échantillons sont automatiquement résolus dans cette texture (non multisample) à la fin du passage de rendu. Lors du rendu dans des tampons de rendu multisample, c’est le seul moyen d’en extraire un contenu résolu et non multisample. Les textures multi-échantillonnées permettent l’échantillonnage dans les shaders ; pour celles-ci, il s’agit donc simplement d’une option parmi d’autres.
Remarque : lorsque la résolution est activée, les données multi-échantillonnage peuvent ne pas être écrites du tout. Cela signifie que l’ texture() multi-échantillonnage ne doit pas être utilisée par la suite avec des shaders pour l’échantillonnage lorsque l’ resolveTexture() est activée.
Remarque : il s’agit d’une API RHI dont la compatibilité n’est pas entièrement garantie ; voir QRhi pour plus de détails.
Voir également QRhiTextureRenderTargetDescription.
Documentation des fonctions membres
[constexpr noexcept default] QRhiColorAttachment::QRhiColorAttachment()
Crée une description vide d'une pièce jointe de couleur.
QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer)
Crée une description d'attache de couleur qui spécifie renderBuffer comme tampon de couleur associé.
QRhiColorAttachment::QRhiColorAttachment(QRhiTexture *texture)
Crée 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 de cubemap ou couche de tableau). Valeur par défaut : 0.
Voir aussi setLayer().
int QRhiColorAttachment::level() const
Renvoie le niveau de mip. Valeur par défaut : 0.
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 associée à cette couleur ne sera pas utilisée dans le cadre d'un rendu multivue.
Cette fonction a été introduite dans Qt 6.7.
Voir également setMultiViewCount().
QRhiRenderBuffer *QRhiColorAttachment::renderBuffer() const
Renvoie le tampon de rendu auquel fait référence la description de cette pièce jointe, ou ` nullptr ` s'il n'y en a pas.
En pratique, l'association d'un « QRhiRenderBuffer » à un « QRhiColorAttachment » est particulièrement utile lors de la mise en place d'un rendu multisample via un tampon de rendu « color » multisample, qui est ensuite converti en une texture non multisample à la fin du passage de rendu.
Voir également setRenderBuffer().
int QRhiColorAttachment::resolveLayer() const
Renvoie le calque de texture de résolution actuellement défini. 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 également setResolveLevel().
QRhiTexture *QRhiColorAttachment::resolveTexture() const
Renvoie la texture « resolve » référencée par cette description d’attachement, ou ` nullptr ` s’il n’y en a pas.
La définition d’une texture de résolution non nulle s’applique lorsque la pièce jointe fait référence à une texture multisample ou à un tampon de rendu. La valeur « QRhiTexture » renvoyée par la fonction `resolveTexture()` correspond alors à une texture 2D non multisample (ou un tableau de textures) de même taille (mais avec un nombre d’échantillons égal à 1). Le contenu multi-échantillon est automatiquement converti en cette texture à la fin de chaque passe de rendu.
Voir également ` setResolveTexture()`.
void QRhiColorAttachment::setLayer(int layer)
Définit l'index « layer ».
Voir aussi layer().
void QRhiColorAttachment::setLevel(int level)
Définit l'level des mips.
Voir également level().
[since 6.7] void QRhiColorAttachment::setMultiViewCount(int count)
Définit l'count de la vue. Une valeur supérieure à 1 indique que la cible de rendu associée à cette attache de couleur sera utilisée avec le rendu multivue. La valeur par défaut est 0. Les valeurs inférieures à 2 indiquent qu'il n'y a pas de rendu multivue.
Lorsque ` count ` est défini sur ` 2 ` ou plus, l'attachement de couleur doit être associé à un tableau de textures 2D. Les fonctions ` layer()` et ` multiViewCount()` définissent conjointement la plage d'éléments du tableau de textures ciblés lors du rendu multivue.
Par exemple, si layer est 0 et multiViewCount est 2, le tableau de textures doit comporter au moins 2 éléments, et le rendu multivue ciblera les éléments 0 et 1. La variable gl_ViewIndex dans les shaders prend alors la valeur 0 ou 1, où view 0 correspond à l’élément 0 du tableau de textures, et view 1 à l’élément 1 du tableau.
Remarque : définir une valeur de ` count ` supérieure à 1, utiliser un tableau de textures comme ` texture()` et appeler ` beginPass()` sur un ` QRhiTextureRenderTarget ` avec cette attache de couleur implique un rendu multivue pour l’ensemble du passage de rendu. ` multiViewCount()` ne doit pas être défini, sauf si le rendu multivue est souhaité. Le rendu multivue ne peut pas être utilisé avec des types de textures autres que les tableaux de textures 2D. (Bien que les textures 3D puissent fonctionner, selon l’API graphique et le backend, il est néanmoins conseillé aux applications de ne pas s’appuyer sur cette fonctionnalité et d’utiliser uniquement des tableaux de textures 2D comme cibles de rendu pour le rendu multivue.)
Voir GL_OVR_multiview pour plus de détails concernant le rendu multivue. Notez que Qt nécessite également GL_OVR_multiview2 lorsqu’il s’exécute sous OpenGL (ES).
Le rendu multivue n’est disponible que lorsque la fonctionnalité « MultiView » est signalée comme prise en charge par isFeatureSupported().
Remarque : pour des raisons de portabilité, tenez compte des limitations qui existent pour le rendu multivue avec certaines API graphiques. Il est recommandé que les passes de rendu multivue ne s’appuient sur aucune des fonctionnalités que GL_OVR_multiview déclare comme non prises en charge. La seule exception concerne les sorties de l’étape de shader autres que ` gl_Position `, selon gl_ViewIndex: on peut s’y fier (même avec OpenGL) car QRhi ne signale jamais la prise en charge du rendu multivue sans que ` GL_OVR_multiview2 ` soit également présent.
Remarque : le rendumultivue n’est pas pris en charge 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 également multiViewCount().
void QRhiColorAttachment::setRenderBuffer(QRhiRenderBuffer *rb)
Définit l'rb du tampon de rendu.
Remarque : les fonctions ` texture()` et ` renderBuffer()` ne peuvent pas être toutes deux définies (c'est-à-dire ne peuvent pas être non nulles en même temps).
Voir également renderBuffer().
void QRhiColorAttachment::setResolveLayer(int layer)
Définit l'layer de texture à utiliser pour la résolution.
Voir aussi resolveLayer().
void QRhiColorAttachment::setResolveLevel(int level)
Définit l'level de mip de la texture de résolution à utiliser.
Voir aussi resolveLevel().
void QRhiColorAttachment::setResolveTexture(QRhiTexture *tex)
Définit l'tex de la texture de résolution.
tex tex doit ê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 du tableau) de . Le niveau de mip et la couche du tableau sont spécifiés par () et (). resolveLevel resolveLayer
Il existe toutefois une exception : multiview. Lorsque l’attachement de couleur est associé à un tableau de textures et que le mode multivue est activé, la texture de résolution doit également être un tableau de textures comportant suffisamment d’éléments pour toutes les vues. Dans ce cas, tous les éléments correspondant aux 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 multisample pour résoudre automatiquement une texture multisample ou un tampon de rendu à la fin du passage de rendu est souvent préférable à l’utilisation de textures multisample (sans définir de texture de résolution), car cela évite d’avoir à écrire des shaders de fragments dédiés fonctionnant exclusivement avec des textures multisample (sampler2DMS, texelFetch, etc.), et permet au contraire d’utiliser le même shader que si la texture de l’attachement n’était pas multisample dès le départ. Cela se fait au prix d’une ressource supplémentaire (l’ tex non multisample).
Voir également resolveTexture().
void QRhiColorAttachment::setTexture(QRhiTexture *tex)
Définit l'tex de la texture.
Remarque : les paramètres texture() et renderBuffer() ne peuvent pas être tous deux définis (c'est-à-dire ne peuvent pas être non nuls en même temps).
Voir également texture().
QRhiTexture *QRhiColorAttachment::texture() const
Renvoie la texture à laquelle fait référence la description de cette pièce jointe, 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.
