glTexImage1D
Inhaltsverzeichnis
glTexImage1D
Name
glTexImage1D - Spezifiziert ein eindimensionales Texturbild.
Spezifikation
procedure glTexImage1D(target: TGLenum; level: TGLint; internalformat: TGLint; width: TGLsizei;
border: TGLint; format: TGLenum; _type: TGLenum; const pixels: PGLvoid);
Parameter
| target | Gibt den Typ der Textur an. GL_TEXTURE_1D oder GL_PROXY_TEXTURE_1D |
| level | Gibt den Detailgrad für das gewünschte Bild an. level 0 ist das Basisbild. Level n ist die n-te Mipmap reduzierung des Bildes. |
| internalformat | 1 für R 2 für R und A 3 für RGB 4 für RGBA oder eine der folgenden symbolischen Konstanten : |
| width, | Gibt die Breite des Texturbildes an. Diese beinhaltet die Rahmenbreite border, falls mit angegeben. Falls die GL-Version keine NPOT-Größe unterstützt, muß dieser Wert 2^n + 2 * border für eine Integerzahl n sein. Alle Implementationen unterstützen Texturbilder die mindestens 64 Texel breit sind. Die Höhe eines 1D-Texturbildes ist 1. |
| border, | Breite des Rahmens || 0 oder 1 |
| format | Bestimmt das Format der Pixeldaten. Folgende symbolische Werte werden akzeptiert: |
| _type | Bestimmt den Pixeltyp für den Inhalt von pixels. Folgende Typen werden unterstützt: |
| pixels | Die Textur-Image Daten vom Typ, der in format angegeben wurde (Array, in dem die Pixel gespeichert sind) |
Beschreibung
Texturierung bildet einen bestimmten Teil eines Texturbildes auf alle Grafikprimitiven ab, für die Texturierung aktiviert ist.
Zur Aktivierung einer eindimensionalen Textur ruft man glEnable mit dem Parameter GL_TEXTURE_1D auf. Die Deaktivierung erfolgt entsprechend mittels glDisable.
Die Texturbilder werden durch die Funktion glTexImage1D definiert. Die Argumente der Funktion beschreiben die Eigenschaften des Texturbildes wie z.B. Breite, Breite des Randes, LOD-Nummer (siehe glTexParameter) und Anzahl der unterstützten 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_1D 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_1D 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 dem linken Ende des Texturfeldes. Nachfolgende Elemente gehen von links nach rechts durch die verbleibenden Texel im Texturfeld. Das letzte Element entspricht dem rechten Ende des Texturfeldes.
Der format Parameter bestimmt die Zusammenstellung der Elemente aus pixels. Folgende 13 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)
GL_DEPTH_COMPONENT
- Jedes Element ist ein einzelner Tiefenwert. OpenGL wandelt diesen in eine Fließkommazahl um, multipliziert diese mit dem vorzeichenbehafteten Skalierungsfaktor GL_DEPTH_SCALE, addiert den vorzeichenbehafteten Bias GL_DEPTH_BIAS und begrenzt auf den Bereich [0,1] ( 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 mit einem entsprechendem internem 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ären 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 :
Vorausgesetzt cs ist die sRGB-Komponente im Bereich [0,1].
Mann kann als target GL_PROXY_TEXTURE_2D oder GL_PROXY_TEXTURE_CUBE_MAP 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
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 :
- Ersetzung der Farbkomponenten durch die Farbtabelle, die durch GL_COLOR_TABLE definiert wurde, falls aktiviert. Siehe glColorTable.
- Eindimensionale Convolution-Filterung, falls aktiviert. Siehe glConvolutionFilter1D.
Falls ein Convolution-Filter die Breite der Textur ändert ( z.B. durch Abarbeitung mit einem GL_CONVOLUTION_BORDER_MODE von GL_REDUCE ) und OpenGL nicht NPOT-Texturen unterstützt, muss die Breite nach der Filterung 2^n + 2*border für eine Integerzahl n sein. - RGBA-Komponenten können mit GL_POST_CONVOLUTION_c_SCALE multipliziert und mit GL_POST_CONVOLUTION_c_BIAS addiert werden, falls aktiviert. Siehe glPixelTransfer.
- Ersetzung der Farbkomponenten durch die Farbtabelle, die durch GL_POST_CONVOLUTION_COLOR_TABLE definiert wurde, falls aktiviert. Siehe glColorTable.
- Transformation durch die Farbmatrix. Siehe glMatrixMode.
- 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.
- 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 Texturebild in exakt der Art und Weise, wie sie auch glDrawPixels beeinflussen.
Eine Textur die 0 Pixel hoch oder breit 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
GL_PROXY_TEXTURE_1D steht als target zur Verfügung.
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 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
glTexImage1D gibt die eindimensionale Textur der aktuellen, mit glActiveTexture definierten Textur-Einheit an ( oder schon vorher, falls die ARB_multitexture-Erweiterung unterstützt wird ).
Ab OpenGL Version 1.4
GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24 und GL_DEPTH_COMPONENT32 stehen zur Verfügung.
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_1D oder GL_PROXY_TEXTURE_1D ist. (entsprechend der benutzten Funktion)
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 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 target nicht GL_TEXTURE_2D oder GL_PROXY_TEXTURE_2D und internalFormat GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24 oder GL_DEPTH_COMPONENT32 ist.
GL_INVALID_OPERATION wird generiert, falls format GL_DEPTH_COMPONENT' und internalFormat nicht GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24 oder GL_DEPTH_COMPONENT32 ist.
GL_INVALID_OPERATION wird generiert, falls internalFormat GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24 oder GL_DEPTH_COMPONENT32 und format nicht GL_DEPTH_COMPONENT 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 glTexImage1D-Funktion in einem glBegin- und glEnd-Block aufgerufen wird.
Zugehörige Wertrückgaben
glGetTexImage
glIsEnabled mit dem Token GL_TEXTURE_1D.
glGet mit Argument GL_PIXEL_UNPACK_BUFFER_BINDING
Siehe auch
glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexSubImage1D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexImage1D, glCopyTexSubImage1D, glDrawPixels, glGetCompressedTexImage, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
