glTexImage2D-Funktion
Die glTexImage2D-Funktion gibt ein zweidimensionales Texturbild an.
Syntax
void WINAPI glTexImage2D(
GLenum target,
GLint level,
GLint internalformat,
GLsizei width,
GLsizei height,
GLint border,
GLint format,
GLenum type,
const GLvoid *pixels
);
Parameter
-
Ziel
-
Die Zieltextur. Muss GL_TEXTURE_2D sein.
-
level
-
Die LOD-Nummer (Level Of Detail, Detailebene). Ebene 0 ist die Basisbildebene. Ebene n ist die n. verkleinerte MIP-Map.
-
internalformat
-
Die Anzahl der Farbkomponenten in der Textur. Muss 1, 2, 3 oder 4 oder eine der folgenden symbolischen Konstanten sein: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_R3_G3_B2, GL_RGB, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12 oder GL_RGBA16.
-
width
-
Die Breite des Texturbilds. Muss 2n + 2(border) für ein Integer n sein.
-
height
-
Die Höhe des Texturbilds. Muss 2*m* + 2(border) für ein Integer m sein.
-
border
-
Die Breite des Rahmens. Muss entweder 0 oder 1 sein.
-
format
-
Das Format der Pixeldaten. Es kann einer von neun symbolischen Werten sein.
Wert Bedeutung - GL_COLOR_INDEX
Jedes Element ist ein einzelner Wert: ein Farbindex. Er wird in eine Festkommazahl konvertiert (mit einer nicht angegebenen Anzahl von 0 Bits rechts vom binären Komma), je nach Wert und Vorzeichen von GL_INDEX_SHIFT nach links bzw. rechts verschoben und mit GL_INDEX_OFFSET addiert (siehe glPixelTransfer). Der resultierende Index wird mithilfe der 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 in Farbkomponenten konvertiert und an den Bereich [0,1] angefügt. - GL_RED
Jedes Element ist eine einzelne rote Komponente. Sie wird in eine Gleitkommazahl konvertiert und in ein RGBA-Element aufgelöst, indem 0,0 für Grün und Blau und 1,0 als Alphawert angefügt werden. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). - GL_GREEN
Jedes Element ist eine einzelne grüne Komponente. Sie wird in eine Gleitkommazahl konvertiert und in ein RGBA-Element aufgelöst, indem 0,0 für Rot und Blau und 1,0 als Alphawert angefügt werden. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). - GL_BLUE
Jedes Element ist eine einzelne blaue Komponente. Sie wird in eine Gleitkommazahl konvertiert und in ein RGBA-Element aufgelöst, indem 0,0 für Rot und Grün und 1,0 als Alphawert angefügt werden. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). - GL_ALPHA
Jedes Element ist eine einzelne rote Komponente. Sie wird in eine Gleitkommazahl konvertiert und in ein RGBA-Element aufgelöst, indem 0,0 für Rot, Grün und Blau angefügt wird. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). - GL_RGB
Jedes Element ist ein RGB-Tripel. Es wird in eine Gleitkommazahl konvertiert und in ein RGBA-Element aufgelöst, indem 1,0 als Alphawert angefügt wird. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). - GL_RGBA
Jedes Element ist ein vollständiges RGBA-Element. Es wird in eine Gleitkommazahl konvertiert. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). - GL_BGR_EXT
Jedes Pixel ist eine Gruppe von drei Komponenten in dieser Reihenfolge: Blau, Grün, Rot.
GL_BGR_EXT stellt ein Format bereit, das dem Speicherlayout von geräteunabhängigen Windows-Bitmaps (DIBs) entspricht. Daher können Ihre Anwendungen dieselben Daten bei Aufrufen von Windows-Funktionen und OpenGL-Pixelfunktionen verwenden.- GL_BGRA_EXT
Jedes Pixel ist eine Gruppe von vier Komponenten in dieser Reihenfolge: Blau, Grün, Rot, Alpha. GL_BGRA_EXT stellt ein Format bereit, das dem Speicherlayout von geräteunabhängigen Windows-Bitmaps (DIBs) entspricht. Daher können Ihre Anwendungen dieselben Daten bei Aufrufen von Windows-Funktionen und OpenGL-Pixelfunktionen verwenden. - GL_LUMINANCE
Jedes Element ist ein einzelner Luminanzwert. Er wird in eine Gleitkommazahl konvertiert und dann in ein RGBA-Element aufgelöst, indem der Luminanzwert dreimal für Rot, Grün und Blau repliziert und dann 1,0 als Alphawert angefügt wird. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). - GL_LUMINANCE_ALPHA
Jedes Element ist ein Paar aus Luminanz- und Alphawert. Es wird in eine Gleitkommazahl konvertiert und dann in ein RGBA-Element aufgelöst, indem der Luminanzwert dreimal für Rot, Grün und Blau repliziert wird. Jede Komponente wird dann mit dem Skalierungsfaktor GL_c_SCALE (mit Vorzeichen) multipliziert, mit dem Bias GL_c_BIAS (mit Vorzeichen) addiert und an den Bereich [0,1] angefügt (siehe glPixelTransfer). -
type
-
Der Datentyp der Pixeldaten. Die folgenden symbolischen Werte werden akzeptiert: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT und GL_FLOAT.
-
pixels
-
Ein Zeiger auf die Bilddaten im Arbeitsspeicher.
Rückgabewert
Diese Funktion gibt keinen Wert zurück.
Fehlercodes
Die folgenden Fehlercodes können von der glGetError-Funktion abgerufen werden.
| Name | Bedeutung |
|---|---|
|
target war keine GL_TEXTURE_2D. |
|
format war keine akzeptierte Formatkonstante. Es werden nur Formatkonstanten akzeptiert, die nicht GL_STENCIL_INDEX und GL_DEPTH_COMPONENT sind. Eine Liste möglicher Werte finden Sie in der Parameterbeschreibung von format. |
|
type war keine Typkonstante. |
|
type war eine GL_BITMAP, und format war nicht GL_COLOR_INDEX. |
|
level war kleiner als null oder größer als log2max, wobei max der zurückgegebene Wert von GL_MAX_TEXTURE_SIZE ist. |
|
internalformat war nicht 1, 2, 3 oder 4. |
|
width oder „height“ war kleiner als null oder größer als 2 + GL_MAX_TEXTURE_SIZE oder konnte nicht als 2n + 2(border) für einen Integerwert n dargestellt werden. |
|
border war nicht 0 oder 1. |
|
Die Funktion wurde zwischen einem Aufruf von glBegin und dem zugehörigen Aufruf von glEnd aufgerufen. |
Hinweise
Die glTexImage2D-Funktion gibt ein zweidimensionales Texturbild an. Bei der Texturierung wird ein Teil eines angegebenen Texturbilds jedem primitiven Grafiktyp zugeordnet, für den die Texturierung aktiviert wurde. Die zweidimensionale Texturierung wird mithilfe von glEnable und glDisable mit dem GL_TEXTURE_2D-Argument aktiviert bzw. deaktiviert.
Texturbilder werden mit glTexImage2D definiert. Die Argumente beschreiben die Parameter des Texturbilds, z. B. Breite, Höhe, Rahmenbreite, LOD-Nummer (siehe glTexParameter) und Anzahl der bereitgestellten Farbkomponenten. Die letzten drei Argumente beschreiben, wie das Bild im Arbeitsspeicher dargestellt wird. Diese Argumente sind identisch mit den Pixelformaten, die für glDrawPixels verwendet werden.
Die Daten werden aus pixels je nach Typ als Abfolge von Bytes, short- oder long-Integer oder Gleitkommawerte mit einfacher Genauigkeit gelesen – jeweils mit oder ohne Vorzeichen. Diese Werte werden in Abhängigkeit von format in Gruppen von 1, 2, 3 oder 4 Werten zusammengefasst, um Elemente zu bilden. Wenn type den Wert „GL_BITMAP“ hat, werden die Daten als Zeichenfolge von Bytes ohne Vorzeichen gelesen (format muss GL_COLOR_INDEX sein). Jedes Datenbyte wird als acht 1-Bit-Elemente behandelt, wobei die Bitreihenfolge durch GL_UNPACK_LSB_FIRST bestimmt wird (siehe glPixelStore). Eine Beschreibung der zulässigen Werte für den type-Parameter finden Sie unter glDrawPixels.
Ein Texturbild kann in Abhängigkeit von components bis zu vier Komponenten pro Texturelement enthalten. Ein Texturbild mit einer Komponente verwendet nur die rote Komponente der RGBA-Farbe, die aus pixels extrahiert wird. Ein Bild mit zwei Komponenten verwendet die R- und A-Werte. Ein Bild mit drei Komponenten verwendet die R-, G- und B-Werte. Ein Bild mit vier Komponenten verwendet alle RGBA-Komponenten.
Die Texturierung hat im Farbindexmodus keine Auswirkungen.
Das Texturbild kann durch dieselben Datenformate wie die Pixel in einem glDrawPixels-Befehl dargestellt werden, wobei GL_STENCIL_INDEX und GL_DEPTH_COMPONENT nicht verwendet werden können. Die Modi glPixelStore und glPixelTransfer wirken sich auf Texturbilder genau so aus wie auf glDrawPixels.
Ein Texturbild mit einer Breite oder Höhe von 0 (null) gibt die NULL-Textur an. Wenn die NULL-Textur für LOD 0 (Detailebene) angegeben wird, ist dies gleichbedeutend mit einer Deaktivierung der Texturierung.
Die folgenden Funktionen rufen Informationen im Zusammenhang mit glTexImage2D ab:
glIsEnabled mit GL_TEXTURE_2D-Argument
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) |
Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) |
Windows 2000 Server [nur Desktop-Apps] |
| Header |
|
| Bibliothek |
|
| DLL |
|