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 !