QGLContext

La classe QGLContext implémente un contexte de rendu OpenGL. Plus d'informations...

#include <QGLContext>

Voir la position dans l'arbre des classes.

Description détaillée

La classe QGLContext implémente un contexte de rendu OpenGL.

Un contexte de rendu OpenGL est une liste complète de variables d'états pour OpenGL. Le format du contexte de rendu est défini dans le constructeur mais peut aussi être défini plus tard avec setFormat(). Les options de format actuellement définies sont retournées par format() ; les options qui sont demandées sont retournées par requestedFormat(). À noter qu'après la construction d'un objet QGLContext, le contexte actuel OpenGL doit être créé avec un appel explicite à la fonction create(). La fonction makeCurrent() définit ce contexte comme le contexte de rendu courant. On peut définir un non-contexte courant en utilisant doneCurrent(). La fonction reset() va réinitialiser le contexte et le rendre invalide.

On peut examiner les propriétés du contexte avec, par exemple isValid(), isSharing(), initialized(), windowCreated() et overlayTransparentColor().

Si on utilise le double buffering, on peut échanger le contenu de l'écran avec le buffer hors écran en utilisant swapBuffers().

À noter que le QGLContext n'est pas protégé pour le développement parallèle (non thread-safe).

Type

enum QGLContext::BindOptionflags QGLContext::BindOptions

Une liste d'options pour décider de la façon de lier une texture avec bindTexture().

Utilisé par x11 à partir des pixmaps pour choisir si le pixmap peut être lié après retournement sur l'axe des Y ou non.

Utilisé par les moteurs de dessin pour indiquer que la mémoire du pixmap doit être gérée avec le pixmap/image d'où il provient, par exemple, en installant des fonctions pour la destruction.

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

Le type BindOptions est un typedef pour QFlags<BindOption>. Il contient une combinaison OU logique de valeurs de BindOption.

Fonctions membres

QGLContext::QGLContext ( const QGLFormat & format )

Construit un contexte OpenGL avec le format donné spécifiant de multiples options d'affichage pour le contexte.

Si l'implémentation d'OpenGL ou du système de fenêtrage ne peut pas satisfaire toutes les fonctionnalités demandées dans format, la plus proche configuration de fonctionnalités sera utilisée. Après création, la fonction format() va retourner le format actuel obtenu.

À noter qu'après la construction d'un objet QGLContext, create() doit être appelée explicitement pour créer le contexte actuel OpenGL. Le contexte va être invalide s'il n'a pas été possible d'obtenir un contexte OpenGL.

Voir aussi format() et isValid().

QGLContext::~QGLContext () [virtual]

Détruit le contexte OpenGL et libère ses ressources.

bool QGLContext::areSharing ( const QGLContext * context1, const QGLContext * context2 ) [static]

Retourne true si context1 et context2 partagent leurs ressources tels que les textures, les programmes de shader, etc. ; sinon retourne false.

Cette fonction a été introduite dans Qt 4.6.

GLuint QGLContext::bindTexture ( const QImage & image, GLenum target, GLint format, BindOptions options )

Génère et lie une texture OpenGL 2D au contexte courant, créé à partir de image. L'identifiant de la texture générée est retourné et peut être utilisé dans les appels à glBindTexture().

Le paramètre target spécifie la texture voulue. La valeur par défaut est GL_TEXTURE_2D.

Le paramètre format définit le format interne pour la texture. Le format par défaut est GL_RGBA.

Les options de liaisons sont un ensemble d'options utilisées pour savoir comment lier la texture au contexte.

La texture qui est générée est mise en cache, donc plusieurs appels à bindTexture() avec la même QImage vont retourner le même identifiant de texture.

À noter qu'on suppose que les paramètres de glPixelStore() et glPixelTransfer() sont ceux par défaut.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi deleteTexture().

GLuint QGLContext::bindTexture ( const QString & fileName )

Il s'agit d'une fonction surchargée.

Lit le fichier de texture compressé fileName et génère une texture OpenGL 2D à partir de celui-ci.

La fonction peut charger les textures DirectDrawSurface (DDS) dans les formats DXT1, DXT3 et DXT5 DDS si les extensions GL_ARB_texture_compression et GL_EXT_texture_compression_s3tc sont prises en charge.

À partir de 4.6.1, les formats de texture ETC1 peuvent être chargés si l'extension GL_OES_compressed_ETC1_RGB8_texture est prise en charge et que la texture ETC1 a été encapsulée dans le format conteneur PVR. De plus, les textures dans les formats PVRTC2 et PVRTC4 peuvent être chargées si l'extension GL_IMG_texture_compression_pvrtc est prise en charge.

Voir aussi deleteTexture().

GLuint QGLContext::bindTexture ( const QImage & image, GLenum target = GL_TEXTURE_2D, GLint format = GL_RGBA )

Génère et lie une texture OpenGL 2D au contexte courant, créé à partir de image. L'identifiant de texture est retourné et peut être utilisé dans les appels à glBindTexture().

Il s'agit d'une fonction surchargée.

GLuint QGLContext::bindTexture ( const QPixmap & pixmap, GLenum target = GL_TEXTURE_2D, GLint format = GL_RGBA )

Il s'agit d'une fonction surchargée.

Génère et lie une texture OpenGL 2D basée sur pixmap.

GLuint QGLContext::bindTexture ( const QPixmap & pixmap, GLenum target, GLint format, BindOptions options )

Il s'agit d'une fonction surchargée.

Génère et lie une texture OpenGL 2D au contexte courant, créé à partir de pixmap.

Cette fonction a été introduite dans Qt 4.6.

bool QGLContext::chooseContext ( const QGLContext * shareContext = 0 ) [virtual protected]

Cette fonction semi-interne est appelée par create(). Elle crée un identifiant OpenGL dépendant du système qui correspond au format() de shareContext du mieux que possible, retournant true si la fonction réussit ou false si un identifiant approprié n'est pas trouvable.

Sur Windows, elle appelle la fonction virtuelle choosePixelFormat(), qui permet de trouver un identifiant de format de pixel correspondant. Sur X11, elle appelle la fonction virtuelle chooseVisual() qui trouve un visuel X approprié. Sur les autres plateformes, cela peut être différent.

void * QGLContext::chooseMacVisual ( GDHandle handle ) [virtual protected]

Seulement avec Mac OS X : cette fonction virtuelle essaie de trouver un visuel qui correspond au format, réduisant les exigences si le format original ne peut être trouvé.

L'algorithme pour réduire les exigences du format est assez primitif, donc on surchargera cette méthode dans la sous-classe si l'application a des exigences spécifiques sur la sélection du visuel.

L'argument handle est toujours à zéro et n'est pas utilisé

Voir aussi chooseContext().

int QGLContext::choosePixelFormat ( void * dummyPfd, HDC pdc ) [virtual protected]

Seulement avec Win32 : cette fonction virtuelle choisit un format de pixel qui correspond au format OpenGL. À réimplémenter dans la sous-classe si on a besoin un contexte personnalisé.

Attention : les pointeurs dummyPfd et pdc sont utilisés comme PIXELFORMATDESCRIPTOR*. On utilise void pour éviter l'utilisation des types spécifiques à Windows dans les entêtes.

Voir aussi chooseContext().

void * QGLContext::chooseVisual () [virtual protected]

Seulement avec X11 : Cette fonction virtuelle essaie de trouver un visuel qui correspond au format, réduisant les exigences si le format original n'a pas pu être trouvé.

L'algorithme pour réduire les exigences de format est assez primitif, donc on surchargera cette méthode dans la sous-classe si l'application a des exigences spécifiques sur la sélection du visuel.

Voir aussi chooseContext().

bool QGLContext::create ( const QGLContext * shareContext = 0 ) [virtual]

Crée le contexte OpenGL. Retourne true si la fonction réussit dans la création d'un contexte de rendu OpenGL valide pour le périphérique de dessin spécifié dans le constructeur ; sinon retourne false (c'est-à-dire : le contexte n'est pas valide).

Après une création réussie, format() retourne la liste des fonctionnalités du contexte de rendu OpenGL créé.

Si shareContext pointe sur un QGLContext valide, cette méthode va essayer d'établir un partage des listes d'affichages et des objets textures entre ce contexte et le contexte shareContext. À noter que cela peut échouer si les deux contextes ont des formats différents. On utilise isSharing() pour voir si le partage est en place.

Attention : note d'implémentation : l'initialisation des membres de classe C++ est normalement effectuée dans le constructeur de classe. QGLContext est une exception car elle doit être simple à personnaliser. Les fonctions virtuelles chooseContext() (et chooseVisual() pour X11) peuvent être réimplémentées dans une sous-classe pour sélectionner un contexte particulier. Le problème est que les fonctions virtuelles ne sont pas appelées correctement lors de la construction (même si c'est correct en C++) car le C++ construit les hiérarchies de classe de bas en haut. Pour cette raison une fonction create() est nécessaire.

Voir aussi chooseContext(), format() et isValid().

const QGLContext * QGLContext::currentContext () [static]

Retourne le contexte courant, c'est-à-dire le contexte auquel toute commande OpenGL va être envoyée. Retourne 0 si aucun contexte n'est courant.

Voir aussi makeCurrent().

void QGLContext::deleteTexture ( GLuint id )

Retire la texture identifiée par id de la texture mise en cache et appelle glDeleteTextures() pour supprimer la texture du contexte.

Voir aussi bindTexture().

QPaintDevice * QGLContext::device () const

Retourne le périphérique de dessin défini pour ce contexte.

Voir aussi QGLContext::QGLContext().

bool QGLContext::deviceIsPixmap () const [protected]

Retourne true si le périphérique de dessin du contexte est un pixmap ; sinon retourne false.

void QGLContext::doneCurrent () [virtual]

Définit un non-contexte OpenGL comme courant. Normalement, on n'a pas besoin d'appeler cette fonction ; QGLContext l'appelle si nécessaire.

void QGLContext::drawTexture ( const QRectF & target, GLuint textureId, GLenum textureTarget = GL_TEXTURE_2D )

Cette fonction prend en charge les cas d'utilisation suivants :

• Avec OpenGL et OpenGL ES 1.x, la fonction dessine la texture donnée, textureId, sur le rectangle cible donné, target, dans l'espace de coordonnées du modèle d'OpenGL. Le paramètre textureTarget doit être une cible de texture 2D.
• Avec OpenGL et OpenGL ES 2.x, si un dessinateur est actif, hors d'un bloc beginNativePainting / endNativePainting et utilise le moteur de type QPaintEngine::OpenGL2, la fonction va dessiner la texture donnée, textureId, sur le rectangle cible donné, target, en respectant l'état actuel du dessinateur. Cela permet de dessiner une texture avec la coupure, la transformation, les indices de rendu et le mode de composition définis par le dessinateur. À noter que la cible de texture doit être GL_TEXTURE_2D pour ce cas d'utilisation et que c'est le seul cas d'utilisation pris en charge dans OpenGL ES 2.x.

Cette fonction a été introduite dans Qt 4.4.

void QGLContext::drawTexture ( const QPointF & point, GLuint textureId, GLenum textureTarget = GL_TEXTURE_2D )

Cette fonction prend en charge les cas d'utilisation suivants :

• par défaut, la fonction dessine la texture donnée, textureId, au point donné dans l'espace de coordonnées du modèle d'OpenGL. Le paramètre textureTarget doit être une cible de texture 2D ;
• si un dessinateur est actif, hors d'un bloc beginNativePainting / endNativePainting et utilise le moteur de type QPaintEngine::OpenGL2, la fonction va dessiner la texture donnée, textureId, au point donné, en respectant l'état actuel du dessinateur. Cela permet de dessiner une texture avec la coupure, la transformation, les indices de rendu et le mode de composition définis par le dessinateur. À noter que la cible de texture doit être GL_TEXTURE_2D pour ce cas d'utilisation.

Note : cette fonction n'est prise en charge sous aucune version d'OpenGL ES.

Cette fonction a été introduite dans Qt 4.4.

QGLFormat QGLContext::format () const

Retourne le format du framebuffer qui a été obtenu (cela peut être un sous-ensemble de ce qui a été demandé).

Voir aussi setFormat() et requestedFormat().

void * QGLContext::getProcAddress ( const QString & proc ) const

Retourne un pointeur de fonction pointant sur la fonction d'extension OpenGL passée dans proc. Zéro est retourné si le pointeur de la fonction n'a pas pu être obtenu.

bool QGLContext::initialized () const [protected]

Retourne true si ce contexte a été initialisé, c'est-à-dire, si QGLWidget::initializeGL() a été appliqué ; sinon retourne false.

Voir aussi setInitialized().

bool QGLContext::isSharing () const

Retourne true si ce contexte partage son contexte OpenGL avec un autre QGLContext, sinon retourne false. À noter que le partage peut ne pas être pris en charge entre deux contextes de formats différents.

bool QGLContext::isValid () const

Retourne true si le contexte de rendu OpenGL a été créé avec succès ; sinon retourne false.

void QGLContext::makeCurrent () [virtual]

Définit ce contexte comme contexte de rendu OpenGL courant. Toutes les fonctions OpenGL appelées vont agir sur ce contexte tant qu'un autre n'est pas rendu courant.

Dans quelques rares cas, l'appel sous-jacent peut échouer. Si cela se produit, un message d'erreur est envoyé sur stderr.

QColor QGLContext::overlayTransparentColor () const

Si le contexte est un contexte valide dans un plan calque, la fonction retourne la couleur de transparence du plan. Sinon retourne une couleur invalide.

La valeur pixel de la valeur retournée est l'index de la couleur de transparence dans la palette du plan calque. (Naturellement, les couleurs RGB sont vides de sens.)

L'objet QColor retourné va généralement fonctionner comme prévu seulement lorsqu'il est passé aux fonctions QGLWidget::qglColor() ou QGLWidget::qglClearColor(). Sous certaines circonstances, il peut aussi être utilisé pour dessiner des graphismes transparents avec un QPainter. Voir l'exemple examples/opengl/overlay_x11 pour les détails.

QGLFormat QGLContext::requestedFormat () const

Retourne le format du framebuffer qui a été originalement demandé dans le constructeur ou avec setFormat().

Voir aussi format().

void QGLContext::reset ()

Réinitialise le contexte et le rend invalide.

Voir aussi create() et isValid().

void QGLContext::setFormat ( const QGLFormat & format )

Définit un format pour ce contexte. Le contexte est réinitialisé.

On appelle create() pour créer un nouveau contexte OpenGL qui essayera de correspondre au nouveau format.

 QGLContext *cx;
 //  ...
 QGLFormat f;
 f.setStereo(true);
 cx->setFormat(f);
 if (!cx->create())
     exit(); // Aucune prise en charge OpenGL, ou ne peut pas dessiner sur le périphérique de dessin spécifié
 if (!cx->format().stereo())
     exit(); // ne peut pas créer un contexte stéréo

Voir aussi format(), reset() et create().

void QGLContext::setInitialized ( bool on ) [protected]

Si on est true le contexte a été initialisé, c'est-à-dire QGLContext::setInitialized() a été appelé. Si on est false le contexte n'a pas été initialisé.

Voir aussi initialized().

void QGLContext::setTextureCacheLimit ( int size ) [static]

Cette fonction définit la limite du cache de texture à size, exprimé en kilo-octets.

Par défaut, la limite du cache est approximativement 64 MB.

Voir aussi textureCacheLimit().

void QGLContext::setWindowCreated ( bool on ) [protected]

Si on est true le contexte a eu une fenêtre créée pour lui. Si on est false aucune fenêtre n'a été créée pour le contexte.

Voir aussi windowCreated().

void QGLContext::swapBuffers () const [virtual]

Échange le contenu de l'écran avec le buffer hors écran. Fonctionne seulement si le contexte est en mode double buffering.

Voir aussi QGLFormat::setDoubleBuffer().

int QGLContext::textureCacheLimit () [static]

Retourne la limite du cache de texture actuelle en kilo-octets.

Voir aussi setTextureCacheLimit().

bool QGLContext::windowCreated () const [protected]

Retourne true si une fenêtre a été créée pour ce contexte ; sinon retourne false.

Voir aussi setWindowCreated().

Remerciements

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