glReadPixels-Funktion

Die glReadPixels-Funktion liest einen Pixelblock aus dem Framepuffer.

Syntax

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

Parameter

x

Die Fenster x-Koordinate des ersten Pixels, das aus dem Framepuffer gelesen wird. Gibt zusammen mit der y-Koordinate die Position der unteren linken Ecke eines rechteckigen Pixels an.

y

Die Fenster-y-Koordinaten des ersten Pixels, das aus dem Framepuffer gelesen wird. Gibt zusammen mit der x-Koordinate die Position der unteren linken Ecke eines rechteckigen Pixels an.

width

Die Breite des Pixelrechtecks.

height

Die Höhe des Pixelrechtecks. Breiten- und Höhenparameter des Werts "1" entsprechen einem einzelnen Pixel.

format

Das Format der Pixeldaten. Die folgenden symbolischen Werte werden akzeptiert:

Wert Bedeutung
GL _ COLOR _ INDEX
Farbindizes werden aus dem von glReadBufferausgewählten Farbpuffer gelesen. Jeder Index wird in einen festen Punkt konvertiert, je nach Wert und Vorzeichen von GL INDEX SHIFT nach links oder rechts verschoben _ und zu GL INDEX OFFSET _ _ _ hinzugefügt. Wenn GL _ MAP COLOR GL TRUE _ _ ist, werden Indizes durch ihre Zuordnungen in der Tabelle GL _ PIXEL MAP I TO I _ _ _ _ ersetzt.
GL _ STENCIL _ INDEX
Schablonenwerte werden aus dem Schablonenpuffer gelesen. Jeder Index wird in einen festen Punkt konvertiert, je nach Wert und Vorzeichen von GL INDEX SHIFT nach links oder rechts verschoben _ und zu GL INDEX OFFSET _ _ _ hinzugefügt. Wenn GL _ MAP _ STENCIL GL _ TRUE ist, werden Indizes durch ihre Zuordnungen in der Tabelle GL _ PIXEL MAP S TO S _ _ _ _ ersetzt.
GL _ DEPTH _ COMPONENT
Tiefenwerte werden aus dem Tiefenpuffer gelesen. Jede Komponente wird in Gleitkommawerte konvertiert, sodass der Mindesttiefewert 0,0 und der maximale Wert 1,0 zugeordnet wird. Jede Komponente wird dann mit GL _ DEPTH _ SCALE multipliziert, zu GL DEPTH BIAS hinzugefügt _ und schließlich an den Bereich _ [ 0,1 ] gebunden.
GL _ RED, GL _ GREEN, GL _ BLUE, GL _ ALPHA, GL _ RGB, GL _ RGBA, GL _ BGR _ EXT, GL _ BGRA _ EXT, GL _ LUMINANCE, GL _ LUMINANCE _ ALPHA
Die Verarbeitung unterscheidet sich je nachdem, ob Farbpuffer Farbindizes oder RGBA-Farbkomponenten speichern. Wenn Farbindizes gespeichert werden, werden sie aus dem von glReadBufferausgewählten Farbpuffer gelesen. Jeder Index wird in einen festen Punkt konvertiert, je nach Wert und Vorzeichen von GL INDEX SHIFT nach links oder rechts verschoben _ und zu GL INDEX OFFSET _ _ _ hinzugefügt. Indizes werden dann durch die Rot-, Grün-, Blau- und Alphawerte ersetzt, die durch Indizieren der Tabellen GL _ PIXEL MAP I TO _ _ _ _ R, GL PIXEL MAP _ I TO _ _ _ _ G, GL PIXEL MAP I TO B und GL PIXEL MAP I TO _ A _ _ _ _ _ _ _ _ _ abgerufen werden. Wenn RGBA-Farbkomponenten in den Farbpuffern gespeichert werden, werden sie aus dem von glReadBuffer ausgewählten Farbpuffer gelesen. Jede Farbkomponente wird in Gleitkomma konvertiert, sodass die Intensität 0,0 und die vollständige Intensität 1,0 entspricht. Jede Komponente wird dann mit GL c SCALE multipliziert _ und gl c BIAS _ _ _ hinzugefügt, wobei c GL _ RED, GL _ GREEN, GL BLUE und GL _ ALPHA _ ist. Jede Komponente ist an den Bereich [ 0,1 angeklammert. ] Wenn GL _ MAP _ COLOR GL TRUE _ ist, wird jede Farbkomponente c durch ihre Zuordnung in der Tabelle GL _ PIXEL MAP c TO c _ _ _ _ ersetzt, wobei c wieder GL _ RED, GL _ GREEN, GL BLUE und GL ALPHA _ _ ist. Jede Komponente wird auf die Größe ihrer entsprechenden Tabelle skaliert, bevor die Suche ausgeführt wird. Schließlich werden nicht benötigte Daten verworfen. Gl RED _ verwirft beispielsweise die Grün-, Blau- und Alphakomponenten, während GL _ RGB nur die Alphakomponente verwirft. GL _ LUMINANCE berechnet einen einzelnen Komponentenwert als Summe der roten, grünen und blauen Komponenten, und GL _ LUMINANCE _ ALPHA macht den gleichen Wert, während alpha als zweiter Wert bleibt.

type

Der Datentyp der Pixeldaten. Dabei muss es sich um einen der folgenden Werte handeln.

type Indexmaske Komponentenkonvertierung
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) c 1 ] /2
GL _ UNSIGNED _ INT_ 2 1 (2 1) c
GL _ INT 2 1 [(2 1) c 1 ] /2
GL _ FLOAT Keine c

Pixel

Gibt die Pixeldaten zurück.

Rückgabewert

Diese Funktion gibt keinen Wert zurück.

Fehlercodes

Die folgenden Fehlercodes können von der glGetError-Funktion abgerufen werden.

Name Bedeutung
GL _ INVALID _ ENUM
format oder type war kein akzeptierter Wert.
GL _ UNGÜLTIGER _ WERT
Die Breite oder Höhe war negativ.
GL _ INVALID _ OPERATION
Das Format lautete GL _ COLOR _ INDEX, und die Farbpuffer speicherten RGBA- oder BGRA-Farbkomponenten.
GL _ INVALID _ OPERATION
Format war GL _ STENCIL _ INDEX, und es gab keinen Schablonenpuffer.
GL _ INVALID _ OPERATION
Format: GL _ DEPTH _ COMPONENT, und es gab keinen Tiefenpuffer.
GL _ INVALID _ OPERATION
Die Funktion wurde zwischen einem Aufruf von glBegin und dem entsprechenden Aufruf von glEndaufgerufen.

Hinweise

Die glReadPixels-Funktion gibt Pixeldaten aus dem Framepuffer zurück, beginnend mit dem Pixel, dessen untere linke Ecke sich an der Position (x, y) befindet, in den Clientspeicher, beginnend bei den Speicherortpixeln. Mehrere Parameter steuern die Verarbeitung der Pixeldaten, bevor sie in den Clientspeicher platziert werden. Diese Parameter werden mit drei Befehlen festgelegt: glPixelStore, glPixelTransferund glPixelMap. In diesem Thema werden die Auswirkungen auf glReadPixels der meisten, aber nicht aller Parameter beschrieben, die von diesen drei Befehlen angegeben werden.

Die glReadPixels-Funktion gibt Werte von jedem Pixel mit der unteren linken Ecke an (x + i, y + j) für 0 = i < Breite und 0 = j < Höhe zurück. Dieses Pixel wird als das i-th-Pixel in der j-ten Zeile bezeichnet. Pixel werden in Zeilenreihenfolge von der untersten bis zur höchsten Zeile von links nach rechts in jeder Zeile zurückgegeben.

Die oben beschriebenen Verschiebungs-, Skalierungs-, Verzerrungs- und Suchfaktoren werden alle durch glPixelTransferangegeben. Der Inhalt des Nachschlagetabellenverzeichnisses wird von glPixelMapangegeben.

Der letzte Schritt umfasst die Konvertierung der Indizes oder Komponenten in das richtige Format, wie vom Typ angegeben. Wenn das Format GL COLOR INDEX oder GL _ _ _ STENCIL _ INDEX ist und der Typ nicht GL _ FLOAT ist, wird jeder Index mit dem mask-Wert maskiert, der in der folgenden Tabelle angegeben ist. Wenn der Typ GL FLOAT _ ist, wird jeder ganzzahlige Index in ein Gleitkommaformat mit einfacher Genauigkeit konvertiert.

Wenn das Format GL _ RED, GL _ GREEN, GL _ BLUE, GL _ ALPHA, GL _ RGB, GL _ RGBA, GL _ BGR _ EXT, GL _ BGRA _ EXT, GL _ LUMINANCE oder GL _ LUMINANCE _ ALPHA lautet und der Typ nicht GL _ FLOAT ist, wird jede Komponente mit dem in der obigen Tabelle dargestellten Multiplikator multipliziert. Wenn der Typ GL _ FLOAT ist, wird jede Komponente wie besehen übergeben (oder in das Gleitkommaformat mit einfacher Genauigkeit des Clients konvertiert, wenn sie sich von dem von OpenGL verwendeten unterscheidet).

Rückgabewerte werden wie folgt im Arbeitsspeicher platziert. Wenn das Format "GL COLOR _ _ INDEX", "GL _ STENCIL _ INDEX", "GL _ DEPTH _ COMPONENT", "GL _ RED", "GL _ GREEN", "GL _ BLUE", "GL _ ALPHA" oder "GL _ LUMINANCE" lautet, wird ein einzelner Wert zurückgegeben, und die Daten für das i-ten Pixel in der j.th-Zeile werden an position (j )width + i platziert. GL _ RGB und GL _ BGR EXT geben drei Werte _ zurück, GL _ RGBA und GL _ BGRA EXT geben vier Werte _ zurück, und GL _ LUMINANCE _ ALPHA gibt zwei Werte für jedes Pixel zurück, wobei alle Werte einem einzelnen Pixel entsprechen, das zusammenhängenden Raum in Pixel belegt. Storage parameter, die von glPixelStorefestgelegt werden, z. B. GL _ PACK SWAP BYTES und GL PACK _ _ _ _ LSB _ FIRST, beeinflussen die Art und Weise, wie Daten in den Arbeitsspeicher geschrieben werden. Eine Beschreibung finden Sie unter glPixelStore.

Werte für Pixel, die sich außerhalb des Fensters befinden, das mit dem aktuellen OpenGL-Kontext verbunden ist, sind nicht definiert.

Wenn ein Fehler generiert wird, wird keine Änderung am Inhalt von Pixeln vorgenommen.

Die folgende Funktion ruft Informationen im Zusammenhang mit glReadPixels ab:

glGet mit argument GL _ INDEX _ MODE

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client)
Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)
Windows 2000 Server [nur Desktop-Apps]
Header
Gl.h
Bibliothek
Opengl32.lib
DLL
Opengl32.dll

Siehe auch

glBegin

glCopyPixels

glDrawPixels

glEnd

glPixelMap

glPixelStore

glPixelTransfer

glReadBuffer