glDrawPixels

glDrawPixels

Name

glDrawPixels - liest Pixeldaten aus dem Speicher und schreibt diese in den Framebuffer relativ zur aktuellen Rasterposition.

procedure glDrawPixels(width: TGLsizei; height: TGLsizei; 
                       format: TGLenum; _type: TGLenum; 
                       const pixels: PGLvoid);

Parameter

width, height	Beschreibt die Dimensionen des Pixelrechtecks. Die Angaben werden dabei in Pixel gemacht.
format	Bestimmt das Format der Pixeldaten. Folgende symbolische Werte werden akzeptiert: GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, und GL_LUMINANCE_ALPHA
type	Beschreibt den Datentyp der Pixeldaten. Muss einer der Folgenden sein: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, oder GL_FLOAT
pixels	Beschreibt die Pixeldaten die in einem Array gespeichert sind.

Beschreibung

glDrawPixels ließt Pixeldaten aus dem Speicher und schreibt diese in den Framebuffer relativ zur aktuellen Rasterposition. Nutzen Sie glRasterPos um die aktuelle Rasterposition zu setzen. Um die aktuelle Rasterposition abzufragen nutzen Sie glGet mit dem Argument GL_CURRENT_RASTER_POSITION.

Verschiedene Parameter bestimmen des decodieren der Pixeldaten im Speicher und die Verarbeitung der Daten bevor diese im Framebuffer abgelegt werden. Diese Parameter werden mit 4 Befehlen gesetzt: glPixelStore, glPixelTransfer, glPixelMap, und glPixelZoom. Dieser Artikel beschreibt den Effekt vieler, jedoch nicht aller Parameter welche die 4 genannten Befehle auf glDrawPixels haben können.

Die Daten welche aus pixels gelesen werden, werden als Sequenz von vorzeichenlosen bzw. behafteten Bytes, Shortints, Integer oder Fließkommazahlen mit einfacher Genauigkeit angesehen. Bestimmt wird dies über die Typangabe in type. Jeder einzelne dieser Werte wird je nach Wert von format als Farb- oder Tiefenkomponente oder als Index verstanden. Indizes werden immer einzeln behandelt. Farbkomponenten werden als Gruppen von ein bis vier Elementen angesehen. (Dies ist wiederum abhängig von format). Indizes und Farbkomponentengruppen gehören jeweils zu einem Pixel. Wenn type GL_BITMAP ist müssen die Daten vorzeichenlose Ganzzahlen sein und format muss entweder GL_COLOR_INDEX oder GL_STENCIL_INDEX sein. Jedes vorzeichenlose Byte wird als acht 1-Bit Pixel behandelt. Die Bitanordnung wird über GL_UNPACK_LSB_FIRST gesteuert. (siehe glPixelStore)

Es werden width x height Pixel aus dem Speicher gelesen. Begonnen wird an der Stelle auf die pixels zeigt. Standardmäßig werden die Pixel aus angrenzenden Speicherregionen gelesen. Eine Ausnahme tritt nach allen width Pixel ein, wo der Lesepointer zur nächsten 4-Byte-Grenze vorgerückt wird. Die 4-Byte Zeilenausrichtung wird über glPixelStore mit dem Argument GL_UNPACK_ALIGNMENT gesetzt. Die Ausrichtung kann auch zur 1, 2, 4 oder 8-Byte-Grenze geändert werden. Andere Pixelstore Prameter spezifizieren andere Lesepointerschrittweiten (bevor das erste Pixel gelsen wird, aber auch nachdem width Pixel gelesen wurden.)

Die width x height Pixel welche aus dem Speicher gelesen werden, werden alle auf die selbe Art und Weise verarbeitet. Bestimmt wird dies durch diverse Parameter die durch glPixelTransfer und glPixelMap gesetzt werden können. Details dieser Operationen genauso wie der Zielpuffer indem die Pixel gezeichnet werden sollen, werden über das Pixelformat bestimmt. Dieses wiederum wird über den Parameter format angegeben. format kann einen von elf symbolischen Werten annehmen:

GL_COLOR_INDEX

Jedes Pixel ist ein einzelnder Wert, ein Farbindex. Dieser wird in eine Festkommazahl mit einer undefinerten Anzahl an binären Nachkommastellen, unabhängig vom verwendeten Datentyp, konvertiert. Fließkomma-Zahlen werden zu Festkommazahlen. Ganze Zahlen mit oder ohne Vorzeichen werden ebenfalls zu Festkommazahlen konviertiert wobei die Bits für die Nachkommastellen in dem Fall alle 0 sind. Bitmap-Werte werden entweder zu 0.0 oder 1.0 konvertiert.

Jeder Festkommaindex wird dann um GL_INDEX_SHIFT Bits nach links verschoben und dann zu GL_INDEX_OFFSET addiert. Wenn GL_INDEX_SHIFT negativ ist, wird nach rechts verschoben. In beiden Fällen werden undefinierte Bits mit Nullen aufgefüllt.

Wennn sich OpenGL im RGBA-Modus befindet, wird der resultierende Index in ein RGBA-Pixel mithilfe der 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-Tabellen konvertiert. Befindet sich die GL im Color-Index-Modus, und ist GL_MAP_COLOR aktiviert, wird der Index durch den Wert ersetzt, auf den er in der Tabelle GL_PIXEL_MAP_I_TO_I zeigt. Egal ob das Ersetzen des Index vollzogen wurde, oder auch nicht, wird der Integer-Teil des Index mit 2*b-1 AND verknüpft(b ist die Anzahl der Bits im Stencil-Puffer).

Die resultierenden Indices oder RGBA-Farben werden dann zu Fragmenten konvertiert, indem die aktuelle Raster-Positions-Z-Koordinate und Textur-Koordinaten auf jedes Pixel angewendet werden und anschließend die x- und y-Fenster-Koordinaten auf das n-te Fragment so angewendet werden, dass

Datei:glDrawPixels RasterPosToFragment.png

wobei [x(r), y(r)] die aktuelle Rasterposition ist. Diese Pixel werden dann genauso behandelt, wie wenn die Fragmente durch rasterisieren von Punkten, Linien oder Polygonen erzeugt worden wären. Texturen, Nebel und andere Fragment-Operationen werden durchgeführt, bevor die Fragmente in den Framebuffer geschrieben werden.

GL_STENCIL_INDEX

Jedes Pixel ist ein einzelner Wert, ein Stecil-Index. Dieser wird in eine Festkommazahl mit einer undefinerten Anzahl an binären Nachkommastellen, unabhängig vom verwendeten Datentyp, konvertiert. Fließkomma-Zahlen werden zu Festkommazahlen. Ganze Zahlen mit oder ohne Vorzeichen werden ebenfalls zu Festkommazahlen konviertiert wobei die Bits für die Nachkommastellen in dem Fall alle 0 sind. Bitmap-Werte werden entweder zu 0.0 oder 1.0 konvertiert.

Jeder Festkommaindex wird dann um GL_INDEX_SHIFT Bits nach links verschoben und dann zu GL_INDEX_OFFSET addiert. Wenn GL_INDEX_SHIFT negativ ist, wird nach rechts verschoben. In beiden Fällen werden undefinierte Bits mit Nullen aufgefüllt. Wenn GL_MAP_STENCIL aktiviert ist, wird index durch den Wert ersetzt, auf den index in der Tabelle GL_PIXEL_MAP_S_TO_S zeigt. Egal ob das Ersetzen des Index vollzogen wurde, oder auch nicht, wird der Integer-Teil des Index mit 2*b-1 AND verknüpft(b ist die Anzahl der Bits im Stencil-Puffer), so dass der n-te Index an die Location

Datei:glDrawPixels RasterPosToFragment.png

geschrieben wird,

wobei [x(r),y(r)] die aktuelle Rasterposition ist. Nur der Pixel-Ownership-Test, der Scissor-Test und Stencil-Writemask beeinflussen diesen Schreinvorgang.

GL_DEPTH_COMPONENT

Jedes Pixel ist eine einzelne Depth-Komponente. Fließkomma-Daten werden direkt in ein internes Fließkomma-Format mit undefinierter Präzision konvertiert. Ganze Zahlen mit Vorzeichen werden linear auf das interne Fließkomma-Format gemapped, so dass die größte positive Zahl 1.0 entspricht, und die kleinste negative Zahl -1.0. Ganze Zahlen ohne Vorzeichen werden genauso gemapped: Die größte Zahl wird zu 1.0, 0 wird zu 0.0. Der resultierende Fließkomma-Tiefenwert wird dann mit GL_DEPTH_SCALE multipliziert und zu GL_DEPTH_BIAS adiiert. Das Ergebnis wird auf den [0,1]-Bereich angepasst.

Die resultierenden Depth-Komponenten werden dann zu Fragmenten konvertiert, indem die aktuelle Rasterpositionsfarbe oder der aktuelle Rasterpositionsfarbindex und Texturkoordinaten auf jedes Pixel angewendet werden, und dann die x- und y-Fenster-Koordinaten so auf das n-te Fragment angewendet werden, dass

Datei:glDrawPixels RasterPosToFragment.png

wobei [x(r), y(r)] die aktuelle Rasterposition ist. Diese Pixel werden dann genauso behandelt, wie wenn die Fragmente durch rasterisieren von Punkten, Linien oder Polygonen erzeugt worden wären. Texturen, Nebel und andere Fragment-Operationen werden durchgeführt, bevor die Fragmente in den Framebuffer geschrieben werden.

GL_RGBA

Jedes Pixel wird auf eine Gruppe aus vier Werten abgebildet: Rot, Grün, Blau und Alpha-Wert.

Fließkommazahlen werden in ein internes Fließkommaformat mit unbestimmter Genauigkeit umgewandelt. Vorzeichenbehaftete Integer werden linear in das interne Fließkommaformat umgewandelt, wobei der größtmögliche Wert (MAXINT) auf 1.0 und der kleinstmögliche Wert (MININT) auf -1.0 abgebildet wird. Vorzeichenlose Integer werden ähnlich behandelt. Null wird auf 0.0 abgebildet und der größtmögliche Wert wird auf 1.0 abgebildet. Die resultierenden Fließkommewerte werden dann entsprechend mit GL_RED_SCALE, GL_GREEN_SCALE, GL_BLUE_SCALE bzw. GL_ALPHA_SCALE multipliziert und zu GL_RED_BIAS, GL_GREEN_BIAS, GL_BLUE_BIAS bzw. GL_ALPHA_BIAS addiert. In einem letzten Schritt werden die Resultate noch auf den Wertebereich [0..1] abgebildet.

Hat GL_MAP_COLOR den Wert true, dann werden alle Farbkomponenten anhand der Tabelle GL_PIXEL_MAP_c_TO_c (c ist je nachdem R, G, B oder A) skaliert und anschließend durch den entsprechenden Wert in der Tabelle ersetzt.

Die resultierenden RGBA-Farben werden dann zu Fragmenten konvertiert, indem die aktuelle Z-Koordinate und Textur-Koordinate auf jedes Pixel angewendet werden und anschließend die x und y Koordinaten des Fensters so auf das n-te Fragment angewendet werden, dass

Datei:glDrawPixels RasterPosToFragment.png

wobei [x(r), y(r)] die aktuelle Raster-Position ist. Diese Pixel werden dann genauso behandelt, wie wenn die Fragmente durch rasterisieren von Punkten, Linien oder Polygonen erzeugt worden wären. Texturen, Nebel und andere Fragment-Operationen werden durchgeführt, bevor die Fragmente in den Framebuffer geschrieben werden.

GL_RED

Jedes Pixel besteht aus einer einzelnen roten Farbkomponente. Die Komponente wird in der selben Weise in das interne Fließkommaformat kovertiert wie die Rotkomponente eines RGBA Pixels. Anschließend wird das Pixel in ein RGBA Pixel umgewandelt dessen Grün bzw. Blaukomponente 0.0 und dessen Alphakomponente 1.0 ist. Nach dieser Konvertierung wird das Pixel wie ein normales RGBA Pixel behandelt.

GL_GREEN

Jedes Pixel besteht aus einer einzelnen grünen Farbkomponente. Die Komponente wird in der selben Weise in das interne Fließkommaformat kovertiert wie die Grünkomponente eines RGBA Pixels. Anschließend wird das Pixel in ein RGBA Pixel umgewandelt dessen Rot bzw. Blaukomponente 0.0 und dessen Alphakomponente 1.0 ist. Nach dieser Konvertierung wird das Pixel wie ein normales RGBA Pixel behandelt.

GL_BLUE

Jedes Pixel besteht aus einer einzelnen blauen Farbkomponente. Die Komponente wird in der selben Weise in das interne Fließkommaformat kovertiert wie die Blaukomponente eines RGBA Pixels. Anschließend wird das Pixel in ein RGBA Pixel umgewandelt dessen Grün bzw. Rotkomponente 0.0 und dessen Alphakomponente 1.0 ist. Nach dieser Konvertierung wird das Pixel wie ein normales RGBA Pixel behandelt.

GL_ALPHA

Jedes Pixel besteht aus einer einzelnen Alphakomponente. Die Komponente wird in der selben Weise in das interne Fließkommaformat kovertiert wie die Alphakomponente eines RGBA Pixels. Anschließend wird das Pixel in ein RGBA Pixel umgewandelt dessen RGB-Komponenten alle 0.0 sind. Nach dieser Konvertierung wird das Pixel wie ein normales RGBA Pixel behandelt.

GL_RGB

Jedes Pixel besteht aus einer 3-Komponenten-Gruppe. Die einzelnen Komponenten werden in der selben Weise in das interne Fließkommaformat kovertiert wie die Komponenten eines RGBA Pixels. Anschließend wird das Pixel in ein RGBA Pixel umgewandelt dessen Alphakomponente 1.0 ist. Nach dieser Konvertierung wird das Pixel wie ein normales RGBA Pixel behandelt.

GL_LUMINANCE

Jedes Pixel besteht aus einer einzelnen Helligkeitskomponente. Die Komponente wird in der selben Weise in das interne Fließkommaformat kovertiert wie die Rotkomponente eines RGBA Pixels. Anschließend wird das Pixel in ein RGBA Pixel umgewandelt dessen RGB-Komponenten auf den Konvertierten Helligkeitswert gesetzt sind und dessen Alphakomponente 1.0 ist. Nach dieser Konvertierung wird das Pixel wie ein normales RGBA Pixel behandelt.

GL_LUMINANCE_ALPHA

Jedes Pixel besteht aus einer 2-Komponenten-Gruppe: Zuerst ein Helligkeitswert dann der Alphawert. Die Komponenten werden in der selben Weise in das interne Fließkommaformat kovertiert wie die Rotkomponente eines RGBA Pixels. Anschließend wird das Pixel in ein RGBA Pixel umgewandelt dessen RGB-Komponenten auf den Konvertierten Helligkeitswert gesetzt sind und dessen Alphakomponente auf den konvertierten Alphawert gesetzt ist. Nach dieser Konvertierung wird das Pixel wie ein normales RGBA Pixel behandelt.

Hier nocheinmal eine Zusammenfassung der für den Parameter format akzeptierten Werte:

Format Parameter

Name	Art der Pixeldaten
GL_COLOR_INDEX	Ein Farb-Index
GL_RGB	Eine rote Farbkomponente, gefolgt von einer grünen und einer blauen
GL_RGBA	Eine rote Farbkomponente, gefolgt von einer grünen, einer blauen und eines Alpha-Wertes
GL_RED	Eine rote Farbkomponente
GL_GREEN	Eine gruene Farbkomponente
GL_BLUE	Eine blaue Farbkomponente
GL_ALPHA	Eine Alpha-Wert Farbkomponente
GL_LUMINANCE	Eine Helligkeits-Komponente
GL_LUMINANCE_ALPHA	Eine Helligkeits-Komponente gefolgt von einer Alpha-Wert Farbkomponente
GL_STENCIL_INDEX	Eine Masken- Komponente
GL_DEPTH_COMPONENT	Eine Farbtiefen-Wert Farbkomponente

Der Parameter type gibt an, wieviel Speicherplatz für eine Komponente eines Pixels reserviert wurde

Name	Datentype
GL_UNSIGNED_BYTE	unsigned 8-bit integer
GL_BYTE	signed 8-bit integer
GL_BITMAP	single bits in unsigned 8-bit integers
GL_UNSIGNED_SHORT	unsigned 16-bit integer
GL_SHORT	signed 16-bit integer
GL_UNSIGNED_INT	unsigned 32-bit integer
GL_INT	32-bit integer
GL_FLOAT	single-precision floating point

Beispiel: wenn das Format GL_RGBA ist und als type GL_INT (32 bit) eingegeben wurde, dann braucht jedes Pixel einen Speicher von 16 bytes (4 Komponenten x 4 bytes)

Hinweise

Werte von Pixeln außerhalb des Fensters, das mit dem aktuellen GL-Kontext verbunden ist, sind undefiniert.

Wenn ein Fehler bei der Durchführung der Funktion auftritt, werden keine Veränderungen am Inhalt von pixels durchgeführt.

Fehlermeldungen

GL_INVALID_ENUM wird generiert wenn format oder type ein ungültiger Wert übergeben wird.
GL_INVALID_VALUE wird generiert wenn entweder width oder height negativ ist.
GL_INVALID_OPERATION wird generiert wenn format GL_COLOR_INDEX ist und der Farbpuffer RGBA Werte enthält.
GL_INVALID_OPERATION wird generiert wenn format GL_STENCIL_INDEX ist und kein Schablonen-(/Stencil-)Puffer existiert.
GL_INVALID_OPERATION wird generiert wenn format GL_DEPTH_COMPONENT ist und kein Tiefenpuffer existiert.
GL_INVALID_OPERATION wird generiert wenn glDrawPixels innerhalb eines glBegin-glEnd Blocks aufgerufen wird.

Zugehörige Wertrückgaben

glGet mit Token GL_INDEX_MODE

Siehe auch

glCopyPixels, glReadPixels, glPixelMap, glPixelStore, glPixelTransfer, glReadBuffer