Quelltext betrachten

= 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 ==
{| border=1 rules=all
! ''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: <br>
'''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:<br>
'''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''' liest 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 das 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 gelesen 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 

:[[Bild: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

:[[Bild: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
:[[Bild: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
:[[Bild: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 ===
<div align="center">
{| {{Prettytable_B1}}
! 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 
|- 
|}
</div>

Der Parameter ''type'' gibt an, wieviel Speicherplatz für eine Komponente eines Pixels reserviert wurde<br>
<div align="center">
{| {{Prettytable_B1}}
! Name 
! Datentyp 
|-
|'''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
|-
|'''GL_UNSIGNED_BYTE_3_3_2''' ||  unsigned 8-bit integer
|-
|'''GL_UNSIGNED_BYTE_2_3_3_REV''' ||  unsigned 8-bit integer with reversed component ordering
|-
|'''GL_UNSIGNED_SHORT_5_6_5'''  ||  unsigned 16-bit integer
|-
|'''GL_UNSIGNED_SHORT_5_6_5_REV'''  ||  unsigned 16-bit integer with reversed component ordering
|-
|'''GL_UNSIGNED_SHORT_4_4_4_4'''  ||  unsigned 16-bit integer
|-
|'''GL_UNSIGNED_SHORT_4_4_4_4_REV'''  ||  unsigned 16-bit integer with reversed component ordering
|-
|'''GL_UNSIGNED_SHORT_5_5_5_1'''  ||  unsigned 16-bit integer
|-
|'''GL_UNSIGNED_SHORT_1_5_5_5_REV'''  ||  unsigned 16-bit integer with reversed component ordering
|-
|'''GL_UNSIGNED_INT_8_8_8_8'''  ||  unsigned 32-bit integer
|-
|'''GL_UNSIGNED_INT_8_8_8_8_REV'''  ||  unsigned 32-bit integer with reversed component ordering
|-
|'''GL_UNSIGNED_INT_10_10_10_2'''  ||  unsigned 32-bit integer
|-
|'''GL_UNSIGNED_INT_2_10_10_10_REV'''  ||  unsigned 32-bit integer with reversed component ordering
|-
|}
</div>

'''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.

'''GL_BGR''' und '''GL_BGRA''' sind nur für ''format'' gültig, wenn die OpenGL-Version 1.2 oder höher ist.

'''GL_UNSIGNED_BYTE_3_3_2''', '''GL_UNSIGNED_BYTE_2_3_3_REV''', '''GL_UNSIGNED_SHORT_5_6_5''', '''GL_UNSIGNED_SHORT_5_6_5_REV''', '''GL_UNSIGNED_SHORT_4_4_4_4''', '''GL_UNSIGNED_SHORT_4_4_4_4_REV''', '''GL_UNSIGNED_SHORT_5_5_5_1''', '''GL_UNSIGNED_SHORT_1_5_5_5_REV''', '''GL_UNSIGNED_INT_8_8_8_8''', '''GL_UNSIGNED_INT_8_8_8_8_REV''', '''GL_UNSIGNED_INT_10_10_10_2''' und '''GL_UNSIGNED_INT_2_10_10_10_REV''' sind nur für ''_type'' gültig, wenn die OpenGL-Version 1.2 oder höher ist.



== 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 [[glGet#GL_INDEX_MODE|GL_INDEX_MODE]]

[[glGet]] mit Token [[glGet#GL_CURRENT_RASTER_POSITION|GL_CURRENT_RASTER_POSITION]]

[[glGet]] mit Token [[glGet#GL_CURRENT_RASTER_POSITION_VALID|GL_CURRENT_RASTER_POSITION_VALID]]

[[glGet]] mit Token [[glGet#GL_PIXEL_UNPACK_BUFFER_BINDING|GL_PIXEL_UNPACK_BUFFER_BINDING]]



== Siehe auch ==
[[glCopyPixels]], [[glReadPixels]], [[glPixelMap]], [[glPixelStore]], [[glPixelZoom]], [[glPixelTransfer]], [[glReadBuffer]]

[[Kategorie:GL|DrawPixels]]
[[Kategorie:GL1.0]]