Version vom 29. April 2009, 09:50 Uhr

glTexImage3D

Name

glTexImage3D - Spezifiziert ein dreidimensionales Texturbild.

Spezifikation

procedure glTexImage3D(target: TGLenum; level: TGLint; internalformat: TGLint; width: TGLsizei; 
                       height: TGLsizei; depth: TGLsizei; border: TGLint; format: TGLenum; 
                       _type: TGLenum; const pixels: PGLvoid); 

Parameter

Beschreibung

Texturierung bildet einen bestimmten Teil eines Texturbildes auf alle Grafikprimitiven ab für die Texturierung aktiviert ist.

Um eine 3D-Textur zu aktivieren ruft man glEnable mit dem Parameter GL_TEXTURE_3D auf. Die Deaktivierung erfolgt entsprechend mittels glDisable.

Das Texturbild wird durch die Funktion glTexImage3D definiert. Die Argumente der Funktion beschreiben die Eigenschaften des Texturbildes wie z.B. Breite, Höhe, Tiefe, Breite des Randes, LOD-Nummer (siehe glTexParameter) und Anzahl der unterstützen Farbkomponenten. Die letzten 3 Argumente beschreiben wie das Bild im Speicher abgelegt wird. Die 3 Argumente sind identisch mit denen, die das Pixelformat bei glDrawPixels steuern.

Falls target GL_PROXY_TEXTURE_3D ist, werden keine Daten von data gelesen, sondern der Zustand des Texturbildes neu berechnet, auf Konsistenz überprüft und gegen die Fähigkeiten der Implementation geprüft. Falls die Implementation mit einer Textur der angeforderten Grösse nicht klarkommt, setzt sie jeden Bildzustand auf 0, generiert jedoch keinen Fehler ( siehe glGetError ). Um ein vollständiges Mipmap-Array abzufragen, sollte man level grösser oder gleich 1 wählen.

Falls target GL_TEXTURE_3D ist, werden die Daten aus pixels als Sequenz von vorzeichenlosen oder -behafteten Byte-, Shortint- oder Longint-Werten oder als Fließkommazahlen einfacher Genauigkeit gelesen. Der Typ wird über type festgelegt.
Die ausgelesen Werte werden abhängig von format gruppiert zu Gruppen mit je einem, zwei, drei oder vier Werten. Diese Gruppen entsprechen einem Element.

Wenn type gleich GL_BITMAP ist, werden die Daten als Folge (orig.: "String") von vorzeichenlosen Bytewerten angesehen (wobei format GL_COLOR_INDEX sein muss). Jedes Byte des Datenblocks wird als Gruppe von 8 1-Bit Elementen interpretiert. Die Reihenfolge der Bits wird durch GL_UNPACK_LSB_FIRST (siehe glPixelStore) festgelegt.

Falls ein nichtnull benamtes Pufferobjekt an das GL_PIXEL_UNPACK_BUFFER -target gebunden ist ( siehe glBindBuffer ) während ein Texturbild definiert wird, wird data als Byte-Offset im Datenspeicher des Pufferobjektes behandelt.

Das erste Element entspricht der unteren linken Ecke des Texturbildes. Nachfolgende Elemente laufen von links nach rechts durch die verbleibenden Texel in der untersten Zeile und dann in nachfolgenden höheren Zeilen. Das letzte Element entspricht der oberen rechten Ecke.

Der format Parameter bestimmt die Zusammenstellung der Elemente aus pixels. Folgende 12 möglichen Werte kann format haben:

GL_COLOR_INDEX

Jedes Element entspricht einem einzelnen Wert, dem Farbindex. Jeder Index wird in eine Festkommazahl (mit einer unbestimmten Anzahl 0 Bits rechts vom Komma) konvertiert, abhängig von Wert und Vorzeichen von GL_INDEX_SHIFT bitweise nach rechts bzw. links verschoben und zu GL_INDEX_OFFSET addiert ( siehe glPixelTransfer ). Dann werden die Indizes durch ihre entsprechenden Werte aus den 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 ersetzt und auf das Interval [0, 1] heruntergerechnet.

GL_RED

Jedes Element entspricht einer roten Farbkomponente. Der Wert wird in eine Fließkommazahl konvertiert und zu einem RGBA Wert ergänzt, indem man 0.0 für die beiden anderen Farben und 1.0 für den Alphakanal hinzufügt. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

GL_GREEN

Jedes Element entspricht einer grünen Farbkomponente. Der Wert wird in eine Fließkommazahl konvertiert und zu einem RGBA Wert ergänzt, indem man 0.0 für die beiden anderen Farben und 1.0 für den Alphakanal hinzufügt. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

GL_BLUE

Jedes Element entspricht einer blauen Farbkomponente. Der Wert wird in eine Fließkommazahl konvertiert und zu einem RGBA Wert ergänzt, indem man 0.0 für die beiden anderen Farben und 1.0 für den Alphakanal hinzufügt. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

GL_ALPHA

Jedes Element entspricht einer Alpha-Farbkomponente. Der Wert wird in eine Fließkommazahl konvertiert und zu einem RGBA Wert ergänzt, indem man 0.0 für die drei anderen Farben hinzufügt. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

GL_INTENSITY

Jedes Element entspricht einem einzelnem Intesivitäts-Wert. OpenGL wandelt dieses in eine Fließkommazahl um und setzt es zu einem RGBA-Element zusammen, indem der Intensitätswert drei Mal für Rot, Grün, Blau und Alpha kopiert wird. Jede Komponente wird dann mit dem vorzeichenbehafteten Skalierungsfaktor GL_c_SCALE multipliziert, zu dem vorzeichenbehafteten Bias GL_c_BIAS addiert und auf den Bereich [0,1] begrenzt ( siehe glPixelTransfer ).

GL_RGB GL_BGR

Jedes Element entspricht den drei RGB-Farbwerten. Die Werte werden in Fließkommazahlen konvertiert und zu einem RGBA Wert ergänzt, indem man 1.0 für den Alphakanal hinzufügt. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

GL_RGBA GL_BGRA

Jedes Element enthält alle vier Farbkomponenten. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

GL_LUMINANCE

Jedes Element entspricht einem Helligkeitswert. Der Wert wird in Fließkommazahlen konvertiert und zu einem RGBA Wert ergänzt, indem man den Helligkeitswert drei mal für R, G und B einsetzt und 1.0 für den Alphakanal hinzufügt. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

GL_LUMINANCE_ALPHA

Jedes Element entspricht einem Paar aus Helligkeitswert und Alphawert. Beide Werte werden in Fließkommazahlen konvertiert und zu einem RGBA Wert ergänzt, indem man den Helligkeitswert drei mal für R, G und B einsetzt und den Alphawert hinzufügt. Jede Komponente wird mit GL_c_SCALE multipliziert und zu GL_c_BIAS addiert, und am Schluss auf den Bereich [0,1] begrenzt, wobei c durch R, G, B oder A ersetzt werden soll. (siehe glPixelTransfer)

Lesen Sie den Artikel glDrawPixels um eine Beschreibung der zulässigen Werte für type zu erhalten.

Wenn eine Anwendung die Textur in einer bestimmten Auflösung oder in einem bestimmten Format speichern möchte, kann sie die Auflösung und das Format mit internalFormat abfragen. OpenGL wird eine interne Repräsentation wählen die das gewünschte internalFormat approximiert, aber das Format muß nicht exakt übereinstimmen. ( Die Repräsentationen spezifiziert durch GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB und GL_RGBA müssen exakt übereinstimmen ). Die numerischen Werte 1, 2, 3 und 4 dürfen ebenfalls benutzt werden um die obrigen Repräsentationen zu spezifizieren.

Wenn der Parameter internalFormat eins der generischen gepackten Formate GL_COMPRESSED_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_RGB oder GL_COMPRESSED_RGBA ist, wird OpenGL das interne Format mit der symbolischen Konstante für ein spezifisches internes Format ersetzen und die Textur vor der Speicherung komprimieren. Falls kein entsprechendes internes Format zur Verfügung steht oder OpenGL das Bild aus irgendeinem Grund nicht komprimieren kann, wird das interne Format stattdessen durch ein entsprechendes internes Basisformat ersetzt.

Falls der Parameter internalFormat GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, GL_SRGB8_ALPHA8, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA oder GL_SLUMINANCE8_ALPHA8 ist, wird die Textur behandelt als wäre die roten, grünen, blauen oder Luminance-Komponenten im sRGB-Farbraum kodiert. Jegliche Alpha-Komponente bleibt unverändert. Die Umwandlung von der sRGB kodierten Komponente cs in eine lineare Komponente cl ist :

Datei:Formel sRGB

Vorausgesetzt cs ist die sRGB-Komponente im Bereich [0,1].

Man kann als target GL_PROXY_TEXTURE_3D nutzen um zu überprüfen, ob eine bestimmte Resolution und ein bestimmtes Format akzeptiert werden. Die Implementation wird ihre beste Anpassung für die geforderte Speicherauflösung und das Format aktualisieren und neu berechnen. Um dann den neu berechneten Zustand abzufragen ruft man glGetTexLevelParameter. Falls die Textur nicht gespeichert werden kann wird der Texturzustand auf 0 gesetzt.

Ein Einkomponenten-Texturbild benutzt nur die aus data extrahierte rote Komponente der RGBA-Farbe. Ein Zweikomponenten-Bild benutzt die R und A Werte. Ein Dreikomponenten-Bild benutzt die R, G und B Werte. Ein Vierkomponenten-Bild benutzt alle RGBA-Komponenten.

Tiefentexturen können während der Texturfilterung und -anwendung als LUMINANCE, INTENSITY oder ALPHA-Texturen behandelt werden. Image-based shadowing kann aktiviert werden, indem die r-Koordinaten der Textur mit den Werten der Tiefentextur verglichen werden um ein Boolsches Ergebnis zu erhalten. Für mehr Details beim Texturvergleich siehe glTexParameter.

Verwendungsmöglichkeit

Abseits dem einfachen Laden von Texturen wird diese Funktion auch benutzt um Speicherbereiche für die spätere Verwendung zu reservieren. Ruft man glTexImage mit pixels = nil auf, wird der Speicherbereich zwar angelegt aber nicht gefüllt. Dies kann zum Beispiel gewünscht sein, wenn man einen Screenshot als Textur verwenden möchte ("Render To Texture"). Man kann dann den Framebuffer (=Screenshot) mittels glCopyTexImage in den durch glTexImage reservierten Speicherbereich kopieren. (Siehe dazu auch diesen Thread im Forum)

Hinweise

glTexImage3D war bis zu OpenGL 1.2 nur eine Erweiterung. Deswegen ist bei manchen Chipsätzen die Funktion nur als glTexImage3DEXT verfügbar.

Texturierung hat im Farbindexmodus keinen Effekt.

Falls die ARB_imaging-Erweiterung unterstützt wird dürfen RGBA-Elemente auch in der Image-Pipeline verarbeitet werden. Die folgenden Stufen dürfen an eine RGBA-Farbe angewendet werden, bevor die Farbkomponenten auf den Bereich [0, 1] eingegrenzt werden :

1. Ersetzung der Farbkomponenten durch die Farbtabelle, die durch GL_COLOR_TABLE definiert wurde, falls aktiviert. Siehe glColorTable.
   
2. Ersetzung der Farbkomponenten durch die Farbtabelle, die durch GL_POST_CONVOLUTION_COLOR_TABLE definiert wurde, falls aktiviert. Siehe glColorTable.
   
3. Transformation durch die Farbmatrix. Siehe glMatrixMode.
   
4. RGBA-Komponenten können mit GL_POST_COLOR_MATRIX_c_SCALE multipliziert und mit GL_POST_COLOR_MATRIX_c_BIAS addiert werden, falls aktiviert. Siehe glPixelTransfer.
   
5. Ersetzung der Farbkomponenten durch die Farbtabelle, die durch GL_POST_COLOR_MATRIX_COLOR_TABLE definiert wurde, falls aktiviert. Siehe glColorTable.
   

Das Texturbild kann in den selben Datenformaten vorliegen wie die Pixel bei glDrawPixels ausgenommen GL_STENCIL_INDEX und GL_DEPTH_COMPONENT. glPixelStore und glPixelTransfer beeinflussen das Texturbild in exakt der Art und Weise, wie sie auch glDrawPixels beeinflussen.

Eine Textur die 0 Pixel breit, hoch oder tief ist, stellt die NULL-Textur dar. Wenn die NULL-Textur für die LOD-Stufe 0 spezifiziert wird entspricht das Verhalten dem bei deaktivierter Texturierung.

Änderungen

Folgende Erweiterungen hat die Funktion erfahren:

Ab OpenGL Version 1.1

Andere interne Formate als 1, 2, 3 oder 4 dürfen benutzt werden.

data darf ein Null-Pointer sein. In diesem Fall wird Texturspeicher allokiert um eine Textur der Breite width, der Höhe height und der Tiefe depth aufzunehmen. Man kann dann Sub-Texturen laden um diesen Texturspeicher zu initialisieren. Das Bild ist undefiniert, falls der Nutzer versucht einen nichtinitialisierten Teil des Texturbildes auf eine Primitive anzuwenden.

Ab OpenGL Version 1.2

Die Formate GL_BGR und GL_BGRA und die Typen 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 stehen zur Verfügung.

Ab OpenGL Version 1.3

glTexImage3D gibt die dreidimensionale Textur der aktuellen, mit glActiveTexture definierten Textur-Einheit an ( oder schon vorher, falls die ARB_multitexture-Erweiterung unterstützt wird ).

Ab OpenGL Version 2.0

NPOT-Texturen werden unterstützt ( oder schon vorher, falls die Implementation die GL_ARB_texture_non_power_of_two-Erweiterung unterstützt ).

Ab OpenGL Version 2.1

Die internen Formate GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, GL_SRGB8_ALPHA8, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA und GL_SLUMINANCE8_ALPHA8 stehen zur Verfügung.

Fehlermeldungen

GL_INVALID_ENUM wird generiert wenn target nicht GL_TEXTURE_3D oder GL_PROXY_TEXTURE_3D ist.

GL_INVALID_ENUM wird generiert wenn format ungültige Werte übergeben wurden. Akzeptiert werden alle Formatangaben außer GL_STENCIL_INDEX und GL_DEPTH_COMPONENT

GL_INVALID_ENUM wird generiert wenn type keine gültige Typkonstante übergeben wurde.

GL_INVALID_ENUM wird generiert wenn GL_BITMAP als type und GL_COLOR_INDEX nicht(!) als format angegeben wurde.

GL_INVALID_VALUE wird generiert wenn level kleiner 0 oder größer ld(max) ist, wobei max der Rückgabewert von GL_MAX_TEXTURE_SIZE ist. (ld = Logarithmus Dualis = Basis 2).

GL_INVALID_VALUE wird generiert wenn für internalformat etwas anderes als 1, 2, 3, 4 oder eine der akzeptieren Resolutions- und symbolischen Formatkonstanten angegeben wurde.

GL_INVALID_VALUE wird generiert wenn width, height bzw. depth kleiner als 0 oder größer als 2 + GL_MAX_TEXTURE_SIZE ist, oder die Bedingung 2^k + 2 * border (k=Integerwerte) nicht erfüllt.

GL_INVALID_VALUE wenn border nicht 0 oder 1 ist.

GL_INVALID_OPERATION wird generiert, falls type eine der Konstanten GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5 oder GL_UNSIGNED_SHORT_5_6_5_REV ist und format nicht GL_RGB.

GL_INVALID_OPERATION wird generiert, falls type eine der Konstanten 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 oder GL_UNSIGNED_INT_2_10_10_10_REV und format weder GL_RGBA noch GL_BGRA ist.

GL_INVALID_OPERATION wird generiert, falls format oder internalFormat GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24 oder GL_DEPTH_COMPONENT32 ist.

GL_INVALID_OPERATION wird generiert, falls ein Pufferobjekt-Name ungleich null an das GL_PIXEL_UNPACK_BUFFER-target gebunden ist und der Datenspeicher des Pufferobjektes währenddessen gemappt wird.

GL_INVALID_OPERATION wird generiert, falls ein Pufferobjekt-Name ungleich null an das GL_PIXEL_UNPACK_BUFFER-target gebunden ist und die Daten derart vom Pufferobjekt entpackt werden, dass der gelesene Speicher die Grösse des Speichers der Daten überschreitet.

GL_INVALID_OPERATION wird generiert, falls ein Pufferobjekt-Name ungleich null an das GL_PIXEL_UNPACK_BUFFER-target gebunden ist und data nicht gleichartig auf die Anzahl der Bytes aufgeteilt werden kann, um im Speicher ein Datum abzuspeichern welches durch type angegeben wurde.

GL_INVALID_OPERATION wird generiert wenn die glTexImage3D-Funktion in einem glBegin- und glEnd-Block aufgerufen wird.

Zugehörige Wertrückgaben

glGetTexImage
glIsEnabled mit dem Token GL_TEXTURE_3D
glGet mit Argument GL_PIXEL_UNPACK_BUFFER_BINDING

Siehe auch

glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glGetCompressedTexImage, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter