Signatur
Beschreibung
compressedTexImage3D() legt Speicher für eine Mipmap-Stufe einer 3D-Textur (gl.TEXTURE_3D) oder eines 2D-Textur-Arrays (gl.TEXTURE_2D_ARRAY) an und füllt ihn mit Daten, die bereits in einem GPU-Kompressionsformat vorliegen. Beim Hochladen wird nichts entpackt: Die Blöcke bleiben im Grafikspeicher komprimiert und werden erst beim Abtasten im Shader dekodiert. Das spart Grafikspeicher und Bandbreite, meist um den Faktor 4 bis 8.
Es gibt zwei Varianten:
- Variante 1: Die Daten kommen als
ArrayBufferView(srcData), optional mit Startindex (srcOffset) und Länge (srcLengthOverride). So können Sie mehrere Mipmap-Stufen aus einer einzigen geladenen Datei (z. B. KTX2 oder DDS) herausschneiden, ohne Daten zu kopieren. - Variante 2: Die Daten werden aus einem Puffer gelesen, der an
gl.PIXEL_UNPACK_BUFFERgebunden ist. Sie geben dann nur die GrößeimageSizein Bytes und einen Byte-offsetin diesem Puffer an.
Die komprimierten Formate gehören nicht zum Kern von WebGL 2. Sie aktivieren die passende Erweiterung vorher mit gl.getExtension(), z. B. WEBGL_compressed_texture_s3tc (vor allem Desktop), WEBGL_compressed_texture_etc oder WEBGL_compressed_texture_astc (vor allem Mobilgeräte). Die Konstante für internalformat stammt aus dem Erweiterungsobjekt. Typische Anwendungen sind Texturatlanten als Array-Ebenen (Terrain-Materialien, Sprite-Sheets, Animationsframes) und – bei passender Unterstützung – volumetrische Daten.
Die Datenmenge muss exakt zur Größe passen, die sich aus Format, Breite, Höhe und Tiefe ergibt. Bei blockbasierten Formaten mit 4×4-Blöcken gilt: ceil(width/4) * ceil(height/4) * depth * Bytes pro Block. Pro Array-Ebene wird also einzeln gerechnet. Die Tiefe wird nicht in Blöcke zerlegt (außer bei 3D-ASTC).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $target Pflicht | GLenum | Textur-Ziel: gl.TEXTURE_2D_ARRAY oder gl.TEXTURE_3D. Die meisten komprimierten Formate (S3TC, ETC2, RGTC, BPTC) erlauben nur TEXTURE_2D_ARRAY. |
|
| $level Pflicht | GLint | Mipmap-Stufe; 0 ist das Basisbild, n die n-te Verkleinerung. |
|
| $internalformat Pflicht | GLenum | Komprimiertes Format aus einer Erweiterung, z. B. ext.COMPRESSED_RGBA_S3TC_DXT5_EXT oder ext.COMPRESSED_RGBA8_ETC2_EAC. |
|
| $width Pflicht | GLsizei | Breite der Mipmap-Stufe in Texeln. | |
| $height Pflicht | GLsizei | Höhe der Mipmap-Stufe in Texeln. | |
| $depth Pflicht | GLsizei | Tiefe (bei TEXTURE_3D) bzw. Anzahl der Ebenen (bei TEXTURE_2D_ARRAY). |
|
| $border Pflicht | GLint | 0 | Muss immer 0 sein, sonst entsteht INVALID_VALUE. |
| $srcData | ArrayBufferView | Variante 1: typisiertes Array (meist Uint8Array) mit den komprimierten Blöcken aller Ebenen dieser Mipmap-Stufe. |
|
| $srcOffset | GLuint | 0 | Variante 1: Startindex in srcData, gezählt in Elementen des typisierten Arrays, nicht in Bytes. |
| $srcLengthOverride | GLuint | 0 | Variante 1: Anzahl der zu lesenden Elemente. 0 bedeutet: von srcOffset bis zum Ende der View. |
| $imageSize | GLsizei | Variante 2: Größe der komprimierten Daten in Bytes im gebundenen PIXEL_UNPACK_BUFFER. |
|
| $offset | GLintptr | Variante 2: Byte-Offset im gebundenen PIXEL_UNPACK_BUFFER. |
Rückgabewert
gl.getError() gemeldet (z. B. INVALID_ENUM, INVALID_VALUE, INVALID_OPERATION).