QGLFormat

La classe QGLFormat spécifie le format d'affichage d'un contexte de rendu OpenGL. Plus d'informations...

#include <QGLFormat>

Voir la position dans l'arbre des classes.

Description détaillée

La classe QGLFormat spécifie le format d'affichage d'un contexte de rendu OpenGL.

Un format d'affichage possède plusieurs caractéristiques :

• Double ou simple buffer.
• Buffer de profondeur.
• RGBA ou mode de couleurs indexées.
• Canal alpha.
• Buffer d'accumulation.
• Stencil buffer.
• Buffers stéréo.
• Rendu direct.
• Présence d'un calque.
• Plan de calque.
• Multisample buffers.

On peut aussi spécifier le nombre de bits de profondeur voulu pour le buffer de couleur, le buffer de profondeur, le buffer alpha, le buffer d'accumulation et le stencil buffer avec les fonctions : setRedBufferSize(), setGreenBufferSize(), setBlueBufferSize(), setDepthBufferSize(), setAlphaBufferSize(), setAccumBufferSize() et setStencilBufferSize().

À noter que même si on veut un buffer de profondeur sur 32 bits (par exemple avec setDepthBufferSize(32)), le format qui va être choisi peut ne pas avoir un buffer de profondeur de 32 bits, même s'il y a un format disponible possédant un buffer de profondeur de 32 bits. La principale raison a pour origine l'algorithme de sélection, dépendant du système et de certaines options de format ayant priorité sur les autres.

On crée et indique quelles sont les options de rendu que l'on veut pour un contexte de rendu OpenGL à un objet QGLFormat.

Les pilotes OpenGL ou les cartes accélératrices peuvent ou non prendre en charge des fonctionnalités avancées telles que le canal alpha ou la vision stéréo. Si on demande des fonctionnalités que le pilote/matériel ne peut pas fournir lors de la création d'un QGLWidget, on va avoir un contexte de rendu possédant le plus proche sous-ensemble de fonctionnalités disponibles.

Il y a plusieurs méthodes pour définir les caractéristiques d'affichage d'un contexte de rendu. L'une d'entre elles est de créer un QGLFormat et de le définir comme défaut pour l'application toute entière :

 QGLFormat fmt;
 fmt.setAlpha(true);
 fmt.setStereo(true);
 QGLFormat::setDefaultFormat(fmt);

Ou on peut spécifier le format voulu lors de la création d'une instance de la sous-classe QGLWidget :

 QGLFormat fmt;
 fmt.setDoubleBuffer(false);                 // simple buffer
 fmt.setDirectRendering(false);              // rendu logiciel
 MyGLWidget* myWidget = new MyGLWidget(fmt, ...);

Après que le widget ait été créé, on peut chercher quelles ont été les fonctionnalités que le système a été capable de fournir :

 QGLFormat fmt;
 fmt.setOverlay(true);
 fmt.setStereo(true);
 MyGLWidget* myWidget = new MyGLWidget(fmt, ...);
 if (!myWidget->format().stereo()) {
     // OK, on enlève les lunettes
     if (!myWidget->format().hasOverlay()) {
         qFatal("Cool hardware required");
     }
 }

OpenGL est une marque déposée de Silicon Graphics, Inc. aux États-Unis est dans les autres pays.

Voir aussi QGLContext et QGLWidget.

Type

enum QGLFormat::OpenGLContextProfile

Cette enum décrit les profils de contexte d'OpenGL qui peuvent être spécifiés au contexte implémentant une version OpenGL 3.2 ou supérieur. Ces profils sont différents des profils OpenGL ES.

Cette enum a été introduite ou modifiée dans Qt 4.7.

enum QGLFormat::OpenGLVersionFlagflags QGLFormat::OpenGLVersionFlags

Cette enum décrit les différentes versions d'OpenGL qui sont reconnues par Qt. On utilise la fonction QGLFormat::openGLVersionFlags() pour identifier quelles versions sont prises en charge durant l'exécution.

Voir aussi http://www.opengl.org pour plus d'informations à propos des différentes révisions d'OpenGL.

Cette enum a été introduite ou modifiée dans Qt 4.2.

Le type OpenGLVersionFlags est un typedef pour QFlags<OpenGLVersionFlag>. Il contient une combinaison avec l'opérateur OU logique des valeurs de OpenGLVersionFlag.

Voir aussi openGLVersionFlags().

Fonctions membres

QGLFormat::QGLFormat ()

Construit un objet QGLFormat avec la configuration par défaut suivante :

• Double buffer : activé.
• Buffer de profondeur : activé.
• RGBA : activé (c'est-à-dire les couleurs indexées désactivées).
• Canal alpha : désactivé.
• Buffer d'accumulation : désactivé.
• Stencil buffer : activé.
• Buffers stéréo : désactivé.
• Rendu direct : activé.
• Calque : désactivé.
• Plan : 0 (c'est-à-dire le plan normal).
• Multisample buffers : désactivé.

QGLFormat::QGLFormat ( QGL::FormatOptions options, int plane = 0 )

Crée un objet QGLFormat qui est une copie du format courant defaultFormat().

Si options n'est pas 0, le format par défaut est modifié par les options de format spécifiées. Le paramètre options devrait être des valeurs de QGL::FormatOption combinées avec l'opérateur OU logique.

Ce constructeur permet de spécifier, facilement, un certain format voulu dans les classes dérivées de QGLWidget, par exemple :

 // Le rendu dans MyGLWidget dépend de l'utilisation
 // du stencil buffer et du canal alpha
 MyGLWidget::MyGLWidget(QWidget* parent)
     : QGLWidget(QGLFormat(QGL::StencilBuffer | QGL::AlphaChannel), parent)
 {
     if (!format().stencil())
         qWarning("Could not get stencil buffer; results will be suboptimal");
     if (!format().alpha())
         qWarning("Could not get alpha channel; results will be suboptimal");
     ...
 }

À noter qu'il y a des valeurs de QGL::FormatOption pour définir des paramètres de format activées et désactivées à la fois, par exemple QGL::DepthBuffer et QGL::NoDepthBuffer, QGL::DirectRendering et QGL::IndirectRendering, etc.

Le paramètre plane est par défaut à 0 et correspond au plan avec lequel ce format devra être associé. Les implémentations d'OpenGL ne prennent pas toutes en charge les différents plans de calques.

Voir aussi defaultFormat(), setOption() et setPlane().

QGLFormat::QGLFormat ( const QGLFormat & other )

Construit une copie de other.

QGLFormat::~QGLFormat ()

Détruit le QGLFormat.

bool QGLFormat::accum () const

Retourne true si le buffer d'accumulation est activé ; sinon retourne false. Le buffer d'accumulation est désactivé par défaut.

Voir aussi setAccum() et setAccumBufferSize().

int QGLFormat::accumBufferSize () const

Retourne la taille du buffer d'accumulation.

Voir aussi setAccumBufferSize(), accum() et setAccum().

bool QGLFormat::alpha () const

Retourne true si le buffer alpha du framebuffer est activé ; sinon retourne false. Le buffer alpha est désactivé par défaut.

Voir aussi setAlpha() et setAlphaBufferSize().

int QGLFormat::alphaBufferSize () const

Retourne la taille du buffer alpha.

Voir aussi alpha(), setAlpha() et setAlphaBufferSize().

int QGLFormat::blueBufferSize () const

Retourne la taille du buffer bleu.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi setBlueBufferSize().

QGLFormat QGLFormat::defaultFormat () [static]

Retourne le QGLFormat par défaut pour l'application. Tous les objets QGLWidget qui sont créés utilisent ce format tant qu'un autre n'est pas spécifié, par exemple lors de leurs constructions.

Si aucun format par défaut n'a été défini avec setDefaultFormat(), il est le même que celui créé avec QGLFormat().

Voir aussi setDefaultFormat().

QGLFormat QGLFormat::defaultOverlayFormat () [static]

Retourne le QGLFormat par défaut pour les contextes calques.

Le format de calque par défaut est :

• Double buffer : désactivé.
• Buffer de profondeur : désactivé.
• RGBA : désactivé (c'est-à-dire le mode de couleurs indexées activé).
• Canal alpha : désactivé.
• Buffer d'accumulation : désactivé.
• Stencil buffer : désactivé.
• Buffers stereo : désactivé.
• Rendu direct : activé.
• Calque : désactivé.
• Multisample buffers : désactivé.
• Plan : 1 (c'est-à-dire, le premier plan calque).

Voir aussi setDefaultOverlayFormat() et setDefaultFormat().

bool QGLFormat::depth () const

Retourne true si le buffer d profondeur est activé ; sinon retourne false. Le buffer de profondeur est activé par défaut.

Voir aussi setDepth() et setDepthBufferSize().

int QGLFormat::depthBufferSize () const

Retourne la taille du buffer de profondeur.

Voir aussi depth(), setDepth() et setDepthBufferSize().

bool QGLFormat::directRendering () const

Retourne true si le rendu direct est activé ; sinon retourne false.

Le rendu direct est activé par défaut.

Voir aussi setDirectRendering().

bool QGLFormat::doubleBuffer () const

Retourne true si le double buffering est activé ; sinon retourne false. Le double buffering est activé par défaut.

Voir aussi setDoubleBuffer().

int QGLFormat::greenBufferSize () const

Retourne la taille du buffer vert.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi setGreenBufferSize().

bool QGLFormat::hasOpenGL () [static]

Retourne true si le système de fenêtres prend en charge OpenGL ; sinon retourne false.

Attention : cette fonction ne doit pas être appelée avant que l'objet QApplication ne soit créé.

bool QGLFormat::hasOpenGLOverlays () [static]

Retourne true si le système de fenêtres prend en charge les calques OpenGL ; sinon retourne false.

Attention : cette fonction ne doit pas être appelée avant que l'objet QApplication ne soit créé.

bool QGLFormat::hasOverlay () const

Retourne true si le calque est activé ; sinon retourne false.

Le calque est désactivé par défaut.

Voir aussi setOverlay().

int QGLFormat::majorVersion () const

Retourne la version majeure d'OpenGL.

Cette fonction a été introduite dans Qt 4.7.

Voir aussi setVersion() et minorVersion().

int QGLFormat::minorVersion () const

Retourne la version mineure d'OpenGL.

Cette fonction a été introduite dans Qt 4.7.

Voir aussi setVersion() et majorVersion().

OpenGLVersionFlags QGLFormat::openGLVersionFlags () [static]

Identifie, à l'exécution, quelles versions d'OpenGL sont prises en charge par la plateforme actuelle.

À noter que si la version 1.5 d'OpenGL est prise en charge, les versions inférieures (c'est-à-dire, 1.4 et inférieures) sont aussi prises en charge. Pour identifier la prise en charge d'une fonctionnalité particulière telle que le multitexturing, on teste la version dans laquelle cette fonctionnalité a été implémentée (c'est-à-dire, la version 1.3 dans ce cas) afin de s'adapter au plus large groupe de plateformes.

Cette fonction nécessite un contexte OpenGL valide courant pour fonctionner ; sinon la fonction retournera OpenGL_Version_None.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi hasOpenGL() et hasOpenGLOverlays().

int QGLFormat::plane () const

Retourne le plan de ce format. La valeur pour les plans normaux est 0. La valeur pour le calque est 1, qui indique le premier plan calque.

Voir aussi setPlane() et defaultOverlayFormat().

OpenGLContextProfile QGLFormat::profile () const

Retourne le profil du contexte OpenGL.

Cette fonction a été introduite dans Qt 4.7.

Voir aussi setProfile().

int QGLFormat::redBufferSize () const

Retourne la taille du buffer rouge.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi setRedBufferSize().

bool QGLFormat::rgba () const

Retourne true si le mode de couleurs RGBA est défini. Retourne false si le mode de couleurs indexées est défini. Le mode de couleurs par défaut est RGBA.

Voir aussi setRgba().

bool QGLFormat::sampleBuffers () const

Retourne true si la prise en charge des buffers multisample est activée ; sinon retourne false.

Le buffer multisample est désactivé par défaut.

Voir aussi setSampleBuffers().

int QGLFormat::samples () const

Retourne le nombre d'échantillons par pixel lorsque le multisampling est activé. Par défaut, le plus haut nombre d'échantillons disponible est utilisé.

Voir aussi setSampleBuffers(), sampleBuffers() et setSamples().

void QGLFormat::setAccum ( bool enable )

Si enable est true, le buffer d'accumulation est activé ; sinon le buffer d'accumulation est désactivé.

Le buffer d'accumulation est désactivé par défaut.

Le buffer d'accumulation est utilisé pour créer des effets de flou et d'exposition multiples.

Voir aussi accum() et setAccumBufferSize().

void QGLFormat::setAccumBufferSize ( int size )

Définit la taille voulue pour le buffer d'accumulation. size est la profondeur de bits pour chaque composant RGBA.

Voir aussi accum(), setAccum() et accumBufferSize().

void QGLFormat::setAlpha ( bool enable )

Si enable est true, le buffer alpha est activé ; sinon le buffer alpha est désactivé.

Le buffer alpha est désactivé par défaut.

Le buffer alpha est généralement utilisé pour l'implémentation de la transparence ou de la translucidité. Le A dans RGBA spécifie la transparence d'un pixel.

Voir aussi alpha() et setAlphaBufferSize().

void QGLFormat::setAlphaBufferSize ( int size )

Définit la taille voulue pour le buffer alpha à size. Cette fonction active implicitement le canal alpha.

Voir aussi setRedBufferSize(), setGreenBufferSize() et alphaBufferSize().

void QGLFormat::setBlueBufferSize ( int size )

Définit la taille voulue pour le buffer bleu à size.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi blueBufferSize(), setRedBufferSize(), setGreenBufferSize() et setAlphaBufferSize().

void QGLFormat::setDefaultFormat ( const QGLFormat & f ) [static]

Définit un nouveau QGLFormat par défaut pour l'application à f. Par exemple, pour définir le simple buffering à la place du double buffering, la fonction main() doit contenir un code similaire à :

 QApplication a(argc, argv);
 QGLFormat f;
 f.setDoubleBuffer(false);
 QGLFormat::setDefaultFormat(f);

Voir aussi defaultFormat().

void QGLFormat::setDefaultOverlayFormat ( const QGLFormat & f ) [static]

Définit un nouveau QGLFormat par défaut pour les contextes de calque à f. Ce format est utilisé à chaque fois qu'un QGLWidget est créé avec un format ayant le calque hasOverlay() d'activé.

Par exemple, pour obtenir le double buffering d'un contexte calque (si disponible), on utilise un code similaire à :

 QGLFormat f = QGLFormat::defaultOverlayFormat();
 f.setDoubleBuffer(true);
 QGLFormat::setDefaultOverlayFormat(f);

Comme toujours, on peut savoir, après la création du widget, si l'implémentation d'OpenGL a été capable de fournir le format voulu :

 // ...suite
 MyGLWidget* myWidget = new MyGLWidget(QGLFormat(QGL::HasOverlay), ...);
 if (myWidget->format().hasOverlay()) {
     // Oui, nous avons un calque, vérifions __son__ format:
     QGLContext* olContext = myWidget->overlayContext();
     if (olContext->format().doubleBuffer())
         ; // Oui, nous avons un calque avec double buffer
     else
         ; // Non, seul un calque avec simple buffer est disponible
 }

Voir aussi defaultOverlayFormat().

void QGLFormat::setDepth ( bool enable )

Si enable est true, le buffer de profondeur est activé ; sinon le buffer de profondeur est désactivé.

Le buffer de profondeur est activé par défaut.

Le but d'un buffer de profondeur (ou Z-buffering) est d'enlever les surfaces cachées. Les pixels reçoivent une valeur Z basée sur la distance de la caméra. Un pixel ayant une valeur Z haute est plus proche de la caméra qu'un pixel ayant une valeur Z basse. Cette information est utilisée pour décider si le pixel est dessiné ou non.

Voir aussi depth() et setDepthBufferSize().

void QGLFormat::setDepthBufferSize ( int size )

Définit la profondeur minimale du buffer à size.

Voir aussi depthBufferSize(), setDepth() et depth().

void QGLFormat::setDirectRendering ( bool enable )

Si enable est true, active le rendu direct ; sinon désactive le rendu direct.

Le rendu direct est activé par défaut.

L'activation de cette fonction va permettre à OpenGL d'ignorer le système de fenêtre sous-jacent et de dessiner directement depuis le matériel à l'écran, si cela est pris en charge par le système.

Voir aussi directRendering().

void QGLFormat::setDoubleBuffer ( bool enable )

Si enable est true, active le double buffering ; sinon active le simple buffering.

Le double buffering est activé par défaut.

Le double buffering est une technique où les graphismes sont dessinés dans un buffer hors écran et non directement à l'écran. Lorsque le dessin est fini, le programme appelle une fonction swapBuffers() pour échanger le contenu du buffer avec celui de l'écran. Le résultat est un dessin sans saut d'images et souvent une meilleure performance.

À noter que les contextes ayant un simple buffer ne sont actuellement pas pris en charge avec EGL.

Voir aussi doubleBuffer(), QGLContext::swapBuffers() et QGLWidget::swapBuffers().

void QGLFormat::setGreenBufferSize ( int size )

Définit la taille voulue du buffer vert à size.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi greenBufferSize(), setRedBufferSize(), setBlueBufferSize() et setAlphaBufferSize().

void QGLFormat::setOption ( QGL::FormatOptions opt )

Définit l'option de format à opt.

Voir aussi testOption().

void QGLFormat::setOverlay ( bool enable )

Si enable est true, active le calque ; sinon désactive le calque.

L'activation du calque va forcer QGLWidget la création d'un contexte additionnel dans un calque. Voir la documentation de QGLWidget pour de plus amples informations.

Voir aussi hasOverlay().

void QGLFormat::setPlane ( int plane )

Définit le plan demandé à plane. 0 est le plan normal, 1 le premier calque, 2 le second calque, etc. ; -1, -2, etc. sont les sous-calques.

À noter que contrairement aux autres spécifications de format, les spécifications pour les plans vont parfaitement correspondre. Cela signifie que si on spécifie un plan que l'implémentation sous-jacente d'OpenGL ne peut pas fournir, un QGLWidget invalide va être créé.

Voir aussi plane().

void QGLFormat::setProfile ( OpenGLContextProfile profile )

Définit le profil de contexte OpenGL à profile. Le profile est ignoré si la version d'OpenGL voulue est inférieure à 3.2.

Cette fonction a été introduite dans Qt 4.7.

Voir aussi profile().

void QGLFormat::setRedBufferSize ( int size )

Définit la taille voulue pour le buffer rouge à size.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi redBufferSize(), setGreenBufferSize(), setBlueBufferSize() et setAlphaBufferSize().

void QGLFormat::setRgba ( bool enable )

Si enable est true, active le mode RGBA. Si enable est false, active le mode de couleurs indexées.

Le mode de couleurs par défaut est RGBA.

RGBA est le mode voulu dans la plupart des applications OpenGL. Dans le mode de couleurs RGBA on peut spécifier les couleurs comme ensemble rouge + vert + bleu + alpha.

Dans le mode de couleurs indexées on peut spécifier un index dans une table de correspondance de couleurs.

Voir aussi rgba().

void QGLFormat::setSampleBuffers ( bool enable )

Si enable est true, un contexte OpenGL avec des buffers multisample est choisi ; sinon l'option est ignorée.

Voir aussi sampleBuffers(), setSamples() et samples().

void QGLFormat::setSamples ( int numSamples )

Définit le nombre d'échantillons par pixel voulu, lorsque le multisampling est activé, à numSamples. Par défaut, le plus haut nombre d'échantillons disponible est utilisé.

Voir aussi setSampleBuffers(), sampleBuffers() et samples().

void QGLFormat::setStencil ( bool enable )

Si enable est true, active le stencil buffer ; sinon désactive le stencil buffer.

Le stencil buffer est activé par défaut.

Le stencil buffer masque certaines parties de la zone de dessin afin que ces zones ne soient pas dessinées.

Voir aussi stencil() and setStencilBufferSize().

void QGLFormat::setStencilBufferSize ( int size )

Définit la taille voulue pour le stencil buffer à size.

Voir aussi stencilBufferSize(), setStencil() et stencil().

void QGLFormat::setStereo ( bool enable )

Si enable est true, active le stéréo buffering ; sinon désactive le stéréo buffering.

Le stéréo buffering est désactivé par défaut.

Le stéréo buffering fournit des buffers de couleurs additionnels pour générer des images du point de vue de chaque \oeil.

Voir aussi stereo().

void QGLFormat::setSwapInterval ( int interval )

Définit l'intervalle d'échange voulu. Cela peut être utilisé pour synchroniser le dessin d'OpenGL dans un système de fenêtres au rafraichissement vertical de l'écran. La définition d'un intervalle interval à 0 va désactiver la synchronisation verticale, n'importe quelle valeur supérieure à 0 va activer la synchronisation verticale.

Sous Windows et sous X11, lorsque les extensions WGL_EXT_swap_control et GLX_SGI_video_sync sont utilisées, le paramètre interval peut être utilisé pour définir le nombre minimal d'images qui sont affichées avant l'échange de buffers. En effet, la définition de l'intervalle interval à 10, signifie qu'il y aura 10 réaffichages avant chaque échange de buffers.

Sous Windows, l'extension WGL_EXT_swap_control doit être présente et sous X11 l'extension GLX_SGI_video_sync doit être présente.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi swapInterval().

void QGLFormat::setVersion ( int major, int minor )

Définit la version d'OpenGL aux nombres majeur major et mineur minor. Si un contexte compatible avec la version d'OpenGL demandée ne peut être créé, un contexte compatible avec la version 1.X va être créé à la place.

Cette fonction a été introduite dans Qt 4.7.

Voir aussi majorVersion() et minorVersion().

bool QGLFormat::stencil () const

Retourne true si le stencil buffer est activé ; sinon retourne false. Le stencil buffer est activé par défaut.

Voir aussi setStencil() et setStencilBufferSize().

int QGLFormat::stencilBufferSize () const

Retourne la taille du stencil buffer.

Voir aussi stencil(), setStencil() et setStencilBufferSize().

bool QGLFormat::stereo () const

Retourne true si le stéréo buffering est activé ; sinon retourne false. Le stéréo buffering est désactivé par défaut.

Voir aussi setStereo().

int QGLFormat::swapInterval () const

Retourne l'intervalle d'échange actuellement défini. -1 est renvoyé si la définition d'un intervalle d'échange n'est pas prise en charge par l'implémentation d'OpenGL.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi setSwapInterval().

bool QGLFormat::testOption ( QGL::FormatOptions opt ) const

Retourne true si l'option de format opt est définie ; sinon retourne false.

Voir aussi setOption().

QGLFormat & QGLFormat::operator= ( const QGLFormat & other )

Affecte other à cet objet.

En relation mais non membres de la classe

bool operator!= ( const QGLFormat & a, const QGLFormat & b )

Retourne false si toutes les options des deux objets QGLFormat a et b sont égales ; sinon retourne true.

bool operator== ( const QGLFormat & a, const QGLFormat & b )

Retourne true si toutes les options des deux objets QGLFormat a et b sont égales ; sinon retourne false.

Remerciements

Merci à Alexandre Laurent pour la traduction ainsi qu'à Lo?c Leguay, Jonathan Courtois et Claude Leloup pour leur relecture !