fonction glReadPixels

La fonction glReadPixels lit un bloc de pixels à partir du framebuffer.

Syntaxe

void WINAPI glReadPixels(
   GLint   x,
   GLint   y,
   GLsizei width,
   GLsizei height,
   GLenum  format,
   GLenum  type,
   GLvoid  *pixels
);

Paramètres

x

Coordonnée x de la fenêtre du premier pixel lu à partir du framebuffer. Avec la coordonnée y , spécifie l’emplacement du coin inférieur gauche d’un bloc rectangulaire de pixels.

y

Coordonnées y de la fenêtre du premier pixel lu à partir du framebuffer. Avec la coordonnée x , spécifie l’emplacement du coin inférieur gauche d’un bloc rectangulaire de pixels.

width

Largeur du rectangle de pixels.

height

Hauteur du rectangle de pixels. Les paramètres de largeur et de hauteur de la valeur « 1 » correspondent à un seul pixel.

format

Format des données de pixels. Les valeurs symboliques suivantes sont acceptées :

Valeur Signification
GL_COLOR_INDEX
Les index de couleur sont lus à partir de la mémoire tampon de couleurs sélectionnée par glReadBuffer. Chaque index est converti en point fixe, décalé vers la gauche ou la droite, en fonction de la valeur et du signe de GL_INDEX_SHIFT, puis ajouté à GL_INDEX_OFFSET. Si GL_MAP_COLOR est GL_TRUE, les index sont remplacés par leurs mappages dans la table GL_PIXEL_MAP_I_TO_I.
GL_STENCIL_INDEX
Les valeurs de gabarit sont lues à partir de la mémoire tampon de gabarit. Chaque index est converti en point fixe, décalé vers la gauche ou la droite, en fonction de la valeur et du signe de GL_INDEX_SHIFT, puis ajouté à GL_INDEX_OFFSET. Si GL_MAP_STENCIL est GL_TRUE, les index sont remplacés par leurs mappages dans la table GL_PIXEL_MAP_S_TO_S.
GL_DEPTH_COMPONENT
Les valeurs de profondeur sont lues à partir de la mémoire tampon de profondeur. Chaque composant est converti en virgule flottante de telle sorte que la valeur de profondeur minimale est mappée à 0,0 et la valeur maximale à 1,0. Chaque composant est ensuite multiplié par GL_DEPTH_SCALE, ajouté à GL_DEPTH_BIAS et finalement serré à la plage [0,1].
GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE, GL_LUMINANCE_ALPHA
Le traitement diffère selon que les mémoires tampons de couleur stockent des index de couleurs ou des composants de couleur RVBA. Si les index de couleur sont stockés, ils sont lus à partir de la mémoire tampon de couleurs sélectionnée par glReadBuffer. Chaque index est converti en point fixe, décalé vers la gauche ou la droite, en fonction de la valeur et du signe de GL_INDEX_SHIFT, puis ajouté à GL_INDEX_OFFSET. Les index sont ensuite remplacés par les valeurs rouge, verte, bleue et alpha obtenues en indexant les tables GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B et GL_PIXEL_MAP_I_TO_A. Si les composants de couleur RVBA sont stockés dans les mémoires tampons de couleurs, ils sont lus à partir de la mémoire tampon de couleurs sélectionnée par glReadBuffer. Chaque composant de couleur est converti en virgule flottante de telle sorte que l’intensité zéro est mappée à 0,0 et l’intensité totale correspond à 1,0. Chaque composant est ensuite multiplié par GL_c_SCALE et ajouté à GL_c_BIAS, où c est GL_RED, GL_GREEN, GL_BLUE et GL_ALPHA. Chaque composant est limité à la plage [0,1]. Enfin, si GL_MAP_COLOR est GL_TRUE, chaque composant de couleur c est remplacé par son mappage dans la table GL_PIXEL_MAP_c_TO_c, où c est à nouveau GL_RED, GL_GREEN, GL_BLUE et GL_ALPHA. Chaque composant est mis à l’échelle à la taille de sa table correspondante avant l’exécution de la recherche. Enfin, les données inutiles sont ignorées. Par exemple, GL_RED ignore les composants vert, bleu et alpha, tandis que GL_RGB ignore uniquement le composant alpha. GL_LUMINANCE calcule une valeur de composant unique en tant que somme des composants rouge, vert et bleu, et GL_LUMINANCE_ALPHA fait de même, tout en conservant alpha comme deuxième valeur.

type

Type de données des données de pixels. Il doit s’agir de l’une des valeurs suivantes.

Type Masque d’index Conversion de composants
GL_UNSIGNED_BYTE 281 (281) C
GL_BYTE 271 [(271)c-1]/2
GL_BITMAP 1 1
GL_UNSIGNED_SHORT 2 61 (2 61) C
GL_SHORT 2 51 [(2 51)c1]/2
GL_UNSIGNED_INT_ 2 1 (2 1) C
GL_INT 2 1 [(2 1)c1]/2
GL_FLOAT aucun c

Pixels

Retourne les données de pixels.

Valeur renvoyée

Cette fonction ne retourne pas de valeur.

Codes d’erreur

Les codes d’erreur suivants peuvent être récupérés par la fonction glGetError .

Name Signification
GL_INVALID_ENUM
format ou type n’était pas une valeur acceptée.
GL_INVALID_VALUE
La largeur ou la hauteur était négative.
GL_INVALID_OPERATION
le format était GL_COLOR_INDEX, et les mémoires tampons de couleurs stockaient les composants de couleur RVBA ou BGRA.
GL_INVALID_OPERATION
format était GL_STENCIL_INDEX et il n’y avait pas de mémoire tampon de gabarit.
GL_INVALID_OPERATION
format était GL_DEPTH_COMPONENT et il n’y avait aucune mémoire tampon de profondeur.
GL_INVALID_OPERATION
La fonction a été appelée entre un appel à glBegin et l’appel correspondant à glEnd.

Notes

La fonction glReadPixels retourne les données de pixels du framebuffer, en commençant par le pixel dont l’angle inférieur gauche se trouve à l’emplacement (x, y), dans la mémoire cliente en commençant par les pixels d’emplacement. Plusieurs paramètres contrôlent le traitement des données de pixels avant qu’elles ne sont placées dans la mémoire du client. Ces paramètres sont définis avec trois commandes : glPixelStore, glPixelTransfer et glPixelMap. Cette rubrique décrit les effets sur glReadPixels de la plupart des paramètres spécifiés par ces trois commandes, mais pas tous.

La fonction glReadPixels retourne des valeurs de chaque pixel avec un coin inférieur gauche à (x + i, y + j) pour 0 = largeur i < et 0 = hauteur j<. Ce pixel est considéré comme le iième pixel dans la jième ligne. Les pixels sont retournés dans l’ordre des lignes de la ligne la plus basse à la ligne la plus élevée, de gauche à droite dans chaque ligne.

Les facteurs de décalage, d’échelle, de biais et de recherche décrits ci-dessus sont tous spécifiés par glPixelTransfer. Le contenu de la table de choix est spécifié par glPixelMap.

La dernière étape consiste à convertir les index ou les composants au format approprié, tel que spécifié par type. Si format est GL_COLOR_INDEX ou GL_STENCIL_INDEX et que le type n’est pas GL_FLOAT, chaque index est masqué avec la valeur de masque indiquée dans le tableau suivant. Si type est GL_FLOAT, chaque index entier est converti en format à virgule flottante simple précision.

Si format est GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE ou GL_LUMINANCE_ALPHA et que le type n’est pas GL_FLOAT, chaque composant est multiplié par le multiplicateur indiqué dans le tableau précédent. Si le type est GL_FLOAT, chaque composant est passé en l’état (ou converti au format à virgule flottante simple précision du client s’il est différent de celui utilisé par OpenGL).

Les valeurs de retour sont placées en mémoire comme suit. Si format est GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA ou GL_LUMINANCE, une valeur unique est retournée et les données du iième pixel dans la ligne jth sont placées à l’emplacement (j )width + i. GL_RGB et GL_BGR_EXT retournent trois valeurs, GL_RGBA et GL_BGRA_EXT retournent quatre valeurs, et GL_LUMINANCE_ALPHA retourne deux valeurs pour chaque pixel, toutes les valeurs correspondant à un seul pixel occupant un espace contigu en pixels. Les paramètres de stockage définis par glPixelStore, tels que GL_PACK_SWAP_BYTES et GL_PACK_LSB_FIRST, affectent la façon dont les données sont écrites en mémoire. Pour obtenir une description , consultez glPixelStore .

Les valeurs des pixels qui se trouvent en dehors de la fenêtre connectée au contexte OpenGL actuel ne sont pas définies.

Si une erreur est générée, aucune modification n’est apportée au contenu des pixels.

La fonction suivante récupère les informations relatives à glReadPixels :

glGet avec argument GL_INDEX_MODE

Spécifications

Condition requise Valeur
Client minimal pris en charge
Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge
Windows 2000 Server [applications de bureau uniquement]
En-tête
Gl.h
Bibliothèque
Opengl32.lib
DLL
Opengl32.dll

Voir aussi

glBegin

glCopyPixels

glDrawPixels

glEnd

glPixelMap

glPixelStore

glPixelTransfer

glReadBuffer