glTexSubImage1D-Funktion

Artikel
10/12/2023

Die glTexSubImage1D-Funktion gibt einen Teil eines vorhandenen eindimensionalen Texturbilds an. Sie können mit glTexSubImage1D keine neue Textur definieren.

Syntax

void WINAPI glTexSubImage1D(
         GLenum  target,
         GLint   level,
         GLint   xoffset,
         GLsizei width,
         GLenum  format,
         GLenum  type,
   const GLvoid  *pixels
);

Parameter

Ziel

Die Zieltextur. Muss GL_TEXTURE_1D sein.

level

Die LOD-Nummer (Level Of Detail, Detailebene). Ebene 0 ist das Basisbild. Ebene n ist die n. verkleinerte MIP-Map.

xoffset

Ein Texeloffset in x-Richtung innerhalb des Texturarrays.

width

Die Breite des Texturteilbilds.

format

Das Format der Pixeldaten. Dieser Parameter kann einen der folgenden symbolischen Werte annehmen.

Wert	Bedeutung
GL_COLOR_INDEX	Jedes Element ist ein einzelner Wert: ein Farbindex. Er wird in ein Festkommaformat 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 ein Gleitkommaformat 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 ein Gleitkommaformat 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 ein Gleitkommaformat 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 Alphakomponente. Sie wird in ein Gleitkommaformat 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 ein Gleitkommaformat 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_LUMINANCE	Jedes Element ist ein einzelner Luminanzwert. Er wird in ein Gleitkommaformat 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 ein Gleitkommaformat 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
GL_INVALID_ENUM	target war keine GL_TEXTURE_1D.
GL_INVALID_ENUM	format war keine akzeptierte Konstante.
GL_INVALID_ENUM	type war keine akzeptierte Konstante.
GL_INVALID_ENUM	type war eine GL_BITMAP, und format war nicht GL_COLOR_INDEX.
GL_INVALID_VALUE	level war kleiner als null oder größer als log2max, wobei max der zurückgegebene Wert von GL_MAX_TEXTURE_SIZE ist.
GL_INVALID_VALUE	xoffset war kleiner als b, oder offset + width war größer als wb, wobei w die GL_TEXTURE_WIDTH und b die Breite der GL_TEXTURE_BORDER des Texturbilds ist, das geändert wird. Beachten Sie, dass w zweimal die Rahmenbreite enthält.
GL_INVALID_VALUE	width war kleiner als b, wobei b die Rahmenbreite des Texturarrays ist.
GL_INVALID_VALUE	border war nicht 0 oder 1.
GL_INVALID_OPERATION	Das Texturarray wurde nicht durch einen vorherigen glTexImage1D-Vorgang definiert.
GL_INVALID_OPERATION	Die Funktion wurde zwischen einem Aufruf von glBegin und dem zugehörigen Aufruf von glEnd aufgerufen.

Hinweise

Die eindimensionale Texturierung wird mithilfe von glEnable und glDisable mit dem GL_TEXTURE_1D-Argument für einen primitiven Typ aktiviert. Während der Texturierung wird ein Teil eines angegebenen Texturbilds jedem aktivierten primitiven Typ zugeordnet. Sie verwenden die glTexSubImage1D-Funktion, um ein zusammenhängendes Teilbild eines vorhandenen eindimensionalen Texturbilds für die Texturierung anzugeben.

Die Texel (Texturpixel), auf die durch pixels verwiesen wird, ersetzen einen Bereich des vorhandenen Texturarrays durch x Indizes von xoffset und xoffset + (width 1) (einschließend). Dieser Bereich darf keine Texel außerhalb des Bereichs des ursprünglich angegebenen Texturarrays enthalten.

Das Angeben eines Teilbilds mit einer width von 0 (null) hat keine Auswirkung und löst keinen Fehler aus.

Die Texturierung hat im Farbindexmodus keine Auswirkungen.

Im Allgemeinen können Texturbilder 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.

Die folgenden Funktionen rufen Informationen zu glTexSubImage1D ab:

glGetTexImage

glIsEnabled mit GL_TEXTURE_1D-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	Gl.h
Bibliothek	Opengl32.lib
DLL	Opengl32.dll

Siehe auch

glCopyTexImage1D
glCopyTexImage2D
glCopyTexSubImage1D
glCopyTexSubImage2D
glDrawPixels
glEnable
glFog
glGetTexImage
glIsEnabled
glPixelStore
glPixelTransfer
glTexEnv
glTexGen
glTexImage1D
glTexImage2D
glTexParameter
glTexSubImage2D