pixelsArray = gl.ReadPixels(x, y, width, height, format)
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
#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
#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
#GL_DEPTH_SCALE
multipliziert, zu #GL_DEPTH_BIAS
hinzugefügt und schließlich in den Bereich
(0,1) festgelegt.
#GL_RED
#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
#GL_RED
.
#GL_BLUE
#GL_RED
.
#GL_ALPHA
#GL_RED
.
#GL_RGB
#GL_RED
.
#GL_RGBA
#GL_RED
.
#GL_LUMINANCE
#GL_RED
.
#GL_LUMINANCE_ALPHA
#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.
#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.
#GL_INDEX_MODE