glCopyPixels-Funktion

Artikel
06/13/2023

Die funktion glCopyPixels kopiert Pixel im Framebuffer.

Syntax

void WINAPI glCopyPixels(
   GLint   x,
   GLint   y,
   GLsizei width,
   GLsizei height,
   GLenum  type
);

Parameter

x

Die x-ebenen Fensterkoordinate der unteren linken Ecke des rechteckigen Bereichs der zu kopierenden Pixel.

y

Die Fensterkoordinate für die Y-Ebene der unteren linken Ecke des rechteckigen Bereichs der zu kopierenden Pixel.

width

Die Breite des rechteckigen Bereichs der zu kopierenden Pixel. Darf nicht negativ sein.

height

Die Höhendimension des rechteckigen Bereichs der zu kopierenden Pixel. Darf nicht negativ sein.

type

Gibt an, ob glCopyPixels Farbwerte, Tiefenwerte oder Schablonenwerte kopieren soll. Die zulässigen symbolischen Konstanten sind.

Wert	Bedeutung
GL_COLOR	Die glCopyPixels-Funktion liest Indizes oder RGBA-Farben aus dem Puffer, der derzeit als Lesequellpuffer angegeben ist (siehe glReadBuffer). Wenn Sich OpenGL im Farbindexmodus befindet: Jeder Index, der aus diesem Puffer gelesen wird, wird in ein Festpunktformat mit einer nicht angegebenen Anzahl von Bits rechts neben dem Binärpunkt konvertiert. Jeder Index wird von GL_INDEX_SHIFT Bits nach links verschoben und GL_INDEX_OFFSET hinzugefügt. Wenn GL_INDEX_SHIFT negativ ist, erfolgt die Verschiebung nach rechts. In beiden Fällen füllen null Bits nicht angegebene Bitspeicherorte im Ergebnis aus. Wenn GL_MAP_COLOR true ist, wird der Index durch den Wert ersetzt, auf den er in der Nachschlagetabelle GL_PIXEL_MAP_I_TO_I verweist. Unabhängig davon, ob der Nachschlagen des Index ersetzt wird oder nicht, wird der ganzzahlige Teil des Indexes dann mit2^b 1 versehen, wobei b die Anzahl der Bits in einem Farbindexpuffer ist. Wenn Sich OpenGL im RGBA-Modus befindet: Die Rot-, Grün-, Blau- und Alphakomponenten jedes gelesenen Pixels werden mit nicht spezifizierter Genauigkeit in ein internes Gleitkommaformat konvertiert. Die Konvertierung ordnet den größten darstellbaren Komponentenwert auf 1,0 und den Komponentenwert null auf 0,0 zu. Die resultierenden Gleitkommafarbwerte werden dann mit GL_c_SCALE multipliziert und GL_c_BIAS hinzugefügt, wobei c für die jeweiligen Farbkomponenten ROT, GRÜN, BLAU und ALPHA ist. Die Ergebnisse werden auf den Bereich [0,1] geklemmt. Wenn GL_MAP_COLOR true ist, wird jede Farbkomponente nach der Größe der Nachschlagetabelle GL_PIXEL_MAP_c_TO_c skaliert und dann durch den Wert ersetzt, auf den sie in dieser Tabelle verweist. c ist R, G, B oder A. Die resultierenden Indizes oder RGBA-Farben werden dann in Fragmente konvertiert, indem die aktuelle Rasterposition z-Koordinaten und Texturkoordinaten an jeden Pixel angefügt und dann Fensterkoordinaten (x_r + i, y_r + j) zugewiesen werden, wobei (x_r , y_r ) die aktuelle Rasterposition ist und das Pixel das Pixel in der i-Position in der Zeile j ist. Diese Pixelfragmente werden dann genau wie die Fragmente behandelt, die durch das Rastern von Punkten, Linien oder Polygonen generiert werden. Texturzuordnung, Nebel und alle Fragmentvorgänge werden angewendet, bevor die Fragmente in den Framebuffer geschrieben werden.
GL_DEPTH	Tiefenwerte werden aus dem Tiefenpuffer gelesen und direkt in ein internes Gleitkommaformat mit nicht angegebener Genauigkeit konvertiert. Der resultierende Gleitkommatiefewert wird dann mit GL_DEPTH_SCALE multipliziert und GL_DEPTH_BIAS hinzugefügt. Das Ergebnis wird an den Bereich [0,1] geklemmt. Die resultierenden Tiefenkomponenten werden dann in Fragmente konvertiert, indem die aktuelle Rasterpositionsfarbe oder die aktuelle Farbindex- und Texturkoordinaten an jeden Pixel angefügt werden und dann Fensterkoordinaten (x_r + i, y_r + j) zugewiesen werden, wobei (x_r , y_r ) die aktuelle Rasterposition ist und das Pixel das Pixel in der i-Position in der Zeile j ist. Diese Pixelfragmente werden dann genau wie die Fragmente behandelt, die durch das Rastern von Punkten, Linien oder Polygonen generiert werden. Texturzuordnung, Nebel und alle Fragmentvorgänge werden angewendet, bevor die Fragmente in den Framebuffer geschrieben werden.
GL_STENCIL	Schablonenindizes werden aus dem Schablonenpuffer gelesen und in ein internes Festpunktformat mit einer nicht angegebenen Anzahl von Bits rechts neben dem Binären Punkt konvertiert. Jeder Festpunktindex wird dann von GL_INDEX_SHIFT Bits links verschoben und GL_INDEX_OFFSET hinzugefügt. Wenn GL_INDEX_SHIFT negativ ist, erfolgt die Verschiebung nach rechts. In beiden Fällen füllen null Bits nicht angegebene Bitspeicherorte im Ergebnis aus. Wenn GL_MAP_STENCIL true ist, wird der Index durch den Wert ersetzt, auf den er in der Nachschlagetabelle GL_PIXEL_MAP_S_TO_S verweist. Unabhängig davon, ob der Nachschlagen des Index ersetzt wird oder nicht, wird der ganzzahlige Teil des Indexes dann mit2^b - 1 ediert, wobei b die Anzahl der Bits im Schablonenpuffer ist. Die resultierenden Schablonenindizes werden dann in den Schablonenpuffer geschrieben, sodass der index, der von der i-Position der j-Zeile gelesen wird, an die Position (x_r + i, y_r + j) geschrieben wird, wobei (x_r , y_r ) die aktuelle Rasterposition ist. Nur der Pixelbesitztest, der Scissor-Test und die Schablonenschreibmaske wirken sich auf diese Schreibvorgänge aus.

Wert

Bedeutung

GL_COLOR

Die glCopyPixels-Funktion liest Indizes oder RGBA-Farben aus dem Puffer, der derzeit als Lesequellpuffer angegeben ist (siehe glReadBuffer).
Wenn Sich OpenGL im Farbindexmodus befindet:

Jeder Index, der aus diesem Puffer gelesen wird, wird in ein Festpunktformat mit einer nicht angegebenen Anzahl von Bits rechts neben dem Binärpunkt konvertiert.
Jeder Index wird von GL_INDEX_SHIFT Bits nach links verschoben und GL_INDEX_OFFSET hinzugefügt. Wenn GL_INDEX_SHIFT negativ ist, erfolgt die Verschiebung nach rechts. In beiden Fällen füllen null Bits nicht angegebene Bitspeicherorte im Ergebnis aus.
Wenn GL_MAP_COLOR true ist, wird der Index durch den Wert ersetzt, auf den er in der Nachschlagetabelle GL_PIXEL_MAP_I_TO_I verweist.
Unabhängig davon, ob der Nachschlagen des Index ersetzt wird oder nicht, wird der ganzzahlige Teil des Indexes dann mit2^b 1 versehen, wobei b die Anzahl der Bits in einem Farbindexpuffer ist.

Wenn Sich OpenGL im RGBA-Modus befindet:

Die Rot-, Grün-, Blau- und Alphakomponenten jedes gelesenen Pixels werden mit nicht spezifizierter Genauigkeit in ein internes Gleitkommaformat konvertiert.
Die Konvertierung ordnet den größten darstellbaren Komponentenwert auf 1,0 und den Komponentenwert null auf 0,0 zu.
Die resultierenden Gleitkommafarbwerte werden dann mit GL_c_SCALE multipliziert und GL_c_BIAS hinzugefügt, wobei c für die jeweiligen Farbkomponenten ROT, GRÜN, BLAU und ALPHA ist.
Die Ergebnisse werden auf den Bereich [0,1] geklemmt.
Wenn GL_MAP_COLOR true ist, wird jede Farbkomponente nach der Größe der Nachschlagetabelle GL_PIXEL_MAP_c_TO_c skaliert und dann durch den Wert ersetzt, auf den sie in dieser Tabelle verweist. c ist R, G, B oder A. Die resultierenden Indizes oder RGBA-Farben werden dann in Fragmente konvertiert, indem die aktuelle Rasterposition z-Koordinaten und Texturkoordinaten an jeden Pixel angefügt und dann Fensterkoordinaten (x_r + i, y_r + j) zugewiesen werden, wobei (x_r , y_r ) die aktuelle Rasterposition ist und das Pixel das Pixel in der i-Position in der Zeile j ist. Diese Pixelfragmente werden dann genau wie die Fragmente behandelt, die durch das Rastern von Punkten, Linien oder Polygonen generiert werden. Texturzuordnung, Nebel und alle Fragmentvorgänge werden angewendet, bevor die Fragmente in den Framebuffer geschrieben werden.

GL_DEPTH

Tiefenwerte werden aus dem Tiefenpuffer gelesen und direkt in ein internes Gleitkommaformat mit nicht angegebener Genauigkeit konvertiert. Der resultierende Gleitkommatiefewert wird dann mit GL_DEPTH_SCALE multipliziert und GL_DEPTH_BIAS hinzugefügt. Das Ergebnis wird an den Bereich [0,1] geklemmt.
Die resultierenden Tiefenkomponenten werden dann in Fragmente konvertiert, indem die aktuelle Rasterpositionsfarbe oder die aktuelle Farbindex- und Texturkoordinaten an jeden Pixel angefügt werden und dann Fensterkoordinaten (x_r + i, y_r + j) zugewiesen werden, wobei (x_r , y_r ) die aktuelle Rasterposition ist und das Pixel das Pixel in der i-Position in der Zeile j ist. Diese Pixelfragmente werden dann genau wie die Fragmente behandelt, die durch das Rastern von Punkten, Linien oder Polygonen generiert werden. Texturzuordnung, Nebel und alle Fragmentvorgänge werden angewendet, bevor die Fragmente in den Framebuffer geschrieben werden.

GL_STENCIL

Schablonenindizes werden aus dem Schablonenpuffer gelesen und in ein internes Festpunktformat mit einer nicht angegebenen Anzahl von Bits rechts neben dem Binären Punkt konvertiert. Jeder Festpunktindex wird dann von GL_INDEX_SHIFT Bits links verschoben und GL_INDEX_OFFSET hinzugefügt. Wenn GL_INDEX_SHIFT negativ ist, erfolgt die Verschiebung nach rechts. In beiden Fällen füllen null Bits nicht angegebene Bitspeicherorte im Ergebnis aus. Wenn GL_MAP_STENCIL true ist, wird der Index durch den Wert ersetzt, auf den er in der Nachschlagetabelle GL_PIXEL_MAP_S_TO_S verweist. Unabhängig davon, ob der Nachschlagen des Index ersetzt wird oder nicht, wird der ganzzahlige Teil des Indexes dann mit2^b - 1 ediert, wobei b die Anzahl der Bits im Schablonenpuffer ist. Die resultierenden Schablonenindizes werden dann in den Schablonenpuffer geschrieben, sodass der index, der von der i-Position der j-Zeile gelesen wird, an die Position (x_r + i, y_r + j) geschrieben wird, wobei (x_r , y_r ) die aktuelle Rasterposition ist. Nur der Pixelbesitztest, der Scissor-Test und die Schablonenschreibmaske wirken sich auf diese Schreibvorgänge aus.

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	type war kein akzeptierter Wert.
GL_INVALID_VALUE	Die Breite oder Höhe war negativ.
GL_INVALID_OPERATION	typ war GL_DEPTH und es gab keinen Tiefenpuffer.
GL_INVALID_OPERATION	type war GL_STENCIL und es gab keinen Schablonenpuffer.
GL_INVALID_OPERATION	Die Funktion wurde zwischen einem Aufruf von glBegin und dem entsprechenden Aufruf von glEnd aufgerufen.

Bemerkungen

Die glCopyPixels-Funktion kopiert ein bildschirmorientiertes Rechteck von Pixeln von der angegebenen Framebuffer-Position in eine Region relativ zur aktuellen Rasterposition. Der Vorgang ist nur dann gut definiert, wenn sich der gesamte Pixelquellbereich innerhalb des verfügbar gemachten Teils des Fensters befindet. Ergebnisse von Kopien von außerhalb des Fensters oder aus Bereichen des Fensters, die nicht verfügbar gemacht werden, sind hardwareabhängig und nicht definiert.

Die Parameter x und y geben die Fensterkoordinaten der unteren linken Ecke des zu kopierenden rechteckigen Bereichs an. Die Breiten - und Höhenparameter geben die Dimensionen des zu kopierenden rechteckigen Bereichs an. Sowohl die Breite als auch die Höhe müssen nicht deegativ sein.

Mehrere Parameter steuern die Verarbeitung der Pixeldaten, während sie kopiert werden. Diese Parameter werden mit drei Funktionen festgelegt: glPixelTransfer, glPixelMap und glPixelZoom. In diesem Thema werden die Auswirkungen auf glCopyPixels der meisten, aber nicht aller Parameter beschrieben, die von diesen drei Funktionen angegeben werden.

Die glCopyPixels-Funktion kopiert Werte aus jedem Pixel mit der unteren linken Ecke (x + i, y + j) für 0 = i<width und 0 = j<height. Dieses Pixel soll das i-Pixel in der j-Zeile sein. Pixel werden in Zeilenreihenfolge von der niedrigsten in die höchste Zeile kopiert, von links nach rechts in jeder Zeile.

Der Typparameter gibt an, ob Farb-, Tiefen- oder Schablonendaten kopiert werden sollen.

Die bisher beschriebene Rasterung geht von Pixelzoomfaktoren von 1,0 aus. Wenn Sie glPixelZoom verwenden, um die Pixelzoomfaktoren x und y zu ändern, werden Pixel wie folgt in Fragmente konvertiert. Wenn (x_r , y_r ) die aktuelle Rasterposition ist und sich ein bestimmtes Pixel in der i-Positionin der j-Zeile des Quellpixel-Rechtecks befindet, werden Fragmente für Pixel generiert, deren Mittelpunkt sich im Rechteck mit Ecken befindet.

(x_r) + Zoomen? i, y_r + zoom_yj)

und

(x_r) + Zoomen? (i + 1), y_r + Zoom_y (j + 1))

wo zoomen? ist der Wert von GL_ZOOM_X und Zoom_y ist der Wert von GL_ZOOM_Y.

Die von glPixelStore angegebenen Modi haben keine Auswirkungen auf den Betrieb von glCopyPixels.

Die folgenden Funktionen rufen Informationen im Zusammenhang mit glCopyPixels ab:

glGet mit Argument GL_CURRENT_RASTER_POSITION

glGet mit Argument GL_CURRENT_RASTER_POSITION_VALID

Um das Farbpixel in der unteren linken Ecke des Fensters an die aktuelle Rasterposition zu kopieren, verwenden Sie

glCopyPixels( 0, 0, 1, 1, GL_COLOR );

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
glDepthFunc
glDrawBuffer
glDrawPixels
glEnd
glGet
glPixelMap
glPixelStore
glPixelTransfer
glPixelZoom
glRasterPos
glReadBuffer
glReadPixels
glStencilFunc