Bezeichnung
gl.ReadPixels -- liest einen Pixelblock aus dem Rahmenpuffer
Übersicht
pixelsArray = gl.ReadPixels(x, y, width, height, format)
Beschreibung
gl.ReadPixels() gibt Pixeldaten aus dem Rahmenpuffer zurück, beginnend mit dem Pixel, dessen linke untere Ecke sich an der Position (x, y) in einer Tabelle befindet. Mehrere Parameter steuern die Verarbeitung der Pixeldaten, bevor sie in die Tabelle gestellt werden. Diese Parameter werden mit drei Befehlen eingestellt: gl.PixelStore(), gl.PixelTransfer() und gl.PixelMap(). Diese Referenzseite beschreibt die Auswirkungen auf gl.ReadPixels() der meisten, aber nicht aller durch diese drei Befehle angegebenen Parameter.

gl.ReadPixels() gibt Werte von jedem Pixel mit der linken unteren Ecke bei (x + i, y + j) für 0 <= i < Breite und 0 <= j < Höhe zurück. Dieses Pixel soll das i-te Pixel in der j-ten Zeile sein. Die Pixel werden in Zeilenfolge von der niedrigsten bis zur höchsten Zeile zurückgegeben, von links nach rechts in jeder Zeile.

gl.ReadPixels() verwendet immer den Typ #GL_FLOAT, um die Pixel aus dem Rahmenpuffer zu lesen. Für eine fein abgestimmte Kontrolle über den Datentyp der Pixeldaten können Sie stattdessen gl.ReadPixelsRaw() verwenden. Siehe gl.ReadPixelsRaw für Details.

format gibt das Format für die zurückgegebenen Pixelwerte an; akzeptierte Werte sind:

#GL_COLOR_INDEX
Farbindizes werden aus dem durch gl.ReadBuffer() ausgewählten Farbpuffer gelesen. Jeder Index wird in einen Festpunkt umgewandelt, 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 Festpunkt umgewandelt, 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 ein Gleitkomma umgewandelt, so dass der minimale Tiefenwert auf 0 und der maximale Wert auf 1 abgebildet wird. Jede Komponente wird dann mit #GL_DEPTH_SCALE multipliziert, zu #GL_DEPTH_BIAS hinzugefügt und schließlich in den Bereich (0,1) festgelegt.

#GL_RED
Die Verarbeitung unterscheidet sich je nachdem, ob Farbpuffer Farbindizes oder RGBA-Farbkomponenten speichern. Wenn Farbindizes gespeichert sind, werden sie aus dem durch gl.ReadBuffer() ausgewählten Farbpuffer gelesen. Jeder Index wird in einen Festpunkt umgewandelt, 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 roten, grünen, blauen und alpha-Werte ersetzt, die durch die Indizierung 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 erhalten werden. Jede Tabelle muss die Größe 2^n haben, aber n kann für verschiedene Tabellen unterschiedlich sein. Bevor ein Index verwendet wird, um einen Wert in einer Tabelle der Größe 2^n nachzuschlagen, muss er gegen 2^n - 1 maskiert werden.

Wenn RGBA-Farbkomponenten in den Farbpuffern gespeichert sind, werden sie aus dem durch gl.ReadBuffer() ausgewählten Farbpuffer gelesen. Jede Farbkomponente wird in ein Gleitkomma umgewandelt, so dass die Nullintensität auf 0.0 und die volle Intensität auf 1.0 abgebildet wird. Jede Komponente wird dann mit #GL_c_SCALE multipliziert und zu #GL_c_BIAS hinzugefügt, wobei c ROT, GRÜN, BLAU oder ALPHA ist. Wenn #GL_MAP_COLOR #GL_TRUE ist, wird schließlich jede Komponente auf den Bereich (0,1) festgelegt, auf die Größe der entsprechenden Tabelle skaliert und dann durch ihre Zuordnung in der Tabelle #GL_PIXEL_MAP_c_TO_c, wobei c R, G, B oder A ist.

Nicht benötigte Daten werden dann verworfen. So entsorgt beispielsweise #GL_RED die Grün-, Blau- und Alpha-Komponenten, während #GL_RGB nur die Alpha-Komponente entsorgt. #GL_LUMINANCE berechnet einen Einkomponentenwert als Summe der roten, grünen und blauen Komponenten und #GL_LUMINANCE_ALPHA macht dasselbe, während Alpha als zweiter Wert beibehalten wird. Die Endwerte werden auf den Bereich (0,1) festgelegt.

#GL_GREEN
Siehe oben in #GL_RED.

#GL_BLUE
Siehe oben in #GL_RED.

#GL_ALPHA
Siehe oben in #GL_RED.

#GL_RGB
Siehe oben in #GL_RED.

#GL_RGBA
Siehe oben in #GL_RED.

#GL_LUMINANCE
Siehe oben in #GL_RED.

#GL_LUMINANCE_ALPHA
Siehe oben in #GL_RED.

Die gerade beschriebenen Verschiebungs-, Skalierungs-, Verzerrungs- und Lookup-Faktoren werden alle durch gl.PixelTransfer() angegeben. Die Inhalte der Lookup-Tabelle selbst werden durch die Angabe von gl.PixelMap() angeben.

Die Rückgabewerte werden wie folgt in die Tabelle eingetragen. Wenn format #GL_COLOR_INDEX, #GL_STENCIL_INDEX, #GL_DEPTH_COMPONENT, #GL_RED, #GL_GREEN, #GL_BLUE, #GL_ALPHA oder #GL_LUMINANCE ist, wird ein einzelner Fließkommawert zurückgegeben. #GL_RGB gibt drei Werte zurück, #GL_RGBA gibt vier Werte zurück und #GL_LUMINANCE_ALPHA gibt zwei Werte für jedes Pixel zurück, wobei alle Werte, die einem einzelnen Pixel entsprechen, zusammenhängenden Platz in den Daten belegen. Speicherparameter werden eingestellt durch gl.PixelStore(), wie z.B. #GL_PACK_LSB_FIRST und #GL_PACK_SWAP_BYTES, beeinflussen die Art und Weise, wie Daten in den Speicher geschrieben werden. Siehe gl.PixelStore für Details.

Werte für Pixel, die außerhalb des Fensters liegen, das mit dem aktuellen GL-Kontext verbunden ist, sind undefiniert.

Weitere Informationen finden Sie in einem OpenGL-Referenzhandbuch.

Eingaben
x
gibt die linke Koordinate eines rechteckigen Blocks von Pixeln an
y
gibt die untere Koordinate eines rechteckigen Blocks von Pixeln an
width
Breite des Pixelrechtecks
height
Höhe des Pixelrechtecks
format
Format der Pixeldaten (siehe oben)
Rückgabewerte
pixelsArray
eine Tabelle mit den Pixeldaten
Fehler
#GL_INVALID_ENUM wird erzeugt, wenn format kein akzeptierter Wert ist.

#GL_INVALID_VALUE wird erzeugt, wenn entweder width oder height negativ ist.

#GL_INVALID_OPERATION wird erzeugt, wenn format #GL_COLOR_INDEX ist und die Farbpuffer RGBA-Farbkomponenten speichern.

#GL_INVALID_OPERATION wird erzeugt, wenn format #GL_STENCIL_INDEX ist und es keinen Schablonenpuffer gibt.

#GL_INVALID_OPERATION wird erzeugt, wenn format #GL_DEPTH_COMPONENT ist und es keinen Tiefenpuffer gibt.

#GL_INVALID_OPERATION wird erzeugt, wenn gl.ReadPixels() zwischen gl.Begin() und gl.End() ausgeführt wird.

Verbundene get-operationen
gl.Get() mit dem Argument #GL_INDEX_MODE


Navigation zeigen