WebGLRenderingContext: compressedTexImage[23]D() method
=======================================================

 The **`WebGLRenderingContext.compressedTexImage2D()`**
 and **`WebGL2RenderingContext.compressedTexImage3D()`** methods
 of the WebGL API specify a two- or
 three-dimensional texture image in a compressed format.

 Compressed image formats must be enabled by WebGL extensions before
 using these methods.

Syntax
------


```js
// WebGL 1:
compressedTexImage2D(target, level, internalformat, width, height, border)
compressedTexImage2D(target, level, internalformat, width, height, border, pixels)

// Additionally available in WebGL 2:
// read from buffer bound to gl.PIXEL\_UNPACK\_BUFFER
compressedTexImage2D(target, level, internalformat, width, height, border, imageSize, offset)
compressedTexImage2D(target, level, internalformat, width, height, border, srcData)
compressedTexImage2D(target, level, internalformat, width, height, border, srcData, srcOffset)
compressedTexImage2D(target, level, internalformat, width, height, border, srcData, srcOffset, srcLengthOverride)

// read from buffer bound to gl.PIXEL\_UNPACK\_BUFFER
compressedTexImage3D(target, level, internalformat, width, height, depth, border, imageSize, offset)

compressedTexImage3D(target, level, internalformat, width, height, depth, border, srcData)
compressedTexImage3D(target, level, internalformat, width, height, depth, border, srcData, srcOffset)
compressedTexImage3D(target, level, internalformat, width, height, depth, border, srcData, srcOffset, srcLengthOverride)
```

### Parameters

`target`

 A `GLenum` specifying the binding point (target) of the active texture.
 Possible values for `compressedTexImage2D`:


* `gl.TEXTURE_2D`: A two-dimensional texture.
* `gl.TEXTURE_CUBE_MAP_POSITIVE_X`: Positive X face for a cube-mapped
 texture.
* `gl.TEXTURE_CUBE_MAP_NEGATIVE_X`: Negative X face for a cube-mapped
 texture.
* `gl.TEXTURE_CUBE_MAP_POSITIVE_Y`: Positive Y face for a cube-mapped
 texture.
* `gl.TEXTURE_CUBE_MAP_NEGATIVE_Y`: Negative Y face for a cube-mapped
 texture.
* `gl.TEXTURE_CUBE_MAP_POSITIVE_Z`: Positive Z face for a cube-mapped
 texture.
* `gl.TEXTURE_CUBE_MAP_NEGATIVE_Z`: Negative Z face for a cube-mapped
 texture.

Possible values for `compressedTexImage3D`:

* `gl.TEXTURE_2D_ARRAY`
* `gl.TEXTURE_3D`

`level`

 A `GLint` specifying the level of detail. Level 0 is the base image
 level and level *n* is the n-th mipmap reduction level.


`internalformat`

 A `GLenum` specifying the compressed image format. Compressed image
 formats must be enabled by WebGL extensions before
 using this method. All values are possible for `compressedTexImage2D`. See
 compressed texture formats for which are valid for `compressedTexImage3D`. Possible
 values:


* When using the `WEBGL_compressed_texture_s3tc` extension:
    + `ext.COMPRESSED_RGB_S3TC_DXT1_EXT`
    + `ext.COMPRESSED_RGBA_S3TC_DXT1_EXT`
    + `ext.COMPRESSED_RGBA_S3TC_DXT3_EXT`
    + `ext.COMPRESSED_RGBA_S3TC_DXT5_EXT`
* When using the `WEBGL_compressed_texture_s3tc_srgb` extension:
    + `ext.COMPRESSED_SRGB_S3TC_DXT1_EXT`
    + `ext.COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT`
    + `ext.COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT`
    + `ext.COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT`
* When using the `WEBGL_compressed_texture_etc` extension:
    + `ext.COMPRESSED_R11_EAC`
    + `ext.COMPRESSED_SIGNED_R11_EAC`
    + `ext.COMPRESSED_RG11_EAC`
    + `ext.COMPRESSED_SIGNED_RG11_EAC`
    + `ext.COMPRESSED_RGB8_ETC2`
    + `ext.COMPRESSED_RGBA8_ETC2_EAC`
    + `ext.COMPRESSED_SRGB8_ETC2`
    + `ext.COMPRESSED_SRGB8_ALPHA8_ETC2_EAC`
    + `ext.COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2`
    + `ext.COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2`
* When using the `WEBGL_compressed_texture_pvrtc` extension:
    + `ext.COMPRESSED_RGB_PVRTC_4BPPV1_IMG`
    + `ext.COMPRESSED_RGBA_PVRTC_4BPPV1_IMG`
    + `ext.COMPRESSED_RGB_PVRTC_2BPPV1_IMG`
    + `ext.COMPRESSED_RGBA_PVRTC_2BPPV1_IMG`
* When using the `WEBGL_compressed_texture_etc1` extension:
    + `ext.COMPRESSED_RGB_ETC1_WEBGL`
* When using the `WEBGL_compressed_texture_astc` extension:
    + `ext.COMPRESSED_RGBA_ASTC_4x4_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_5x4_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_5x4_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_5x5_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_5x5_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_6x5_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_6x5_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_6x6_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_6x6_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_8x5_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_8x5_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_8x6_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_8x6_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_8x8_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_8x8_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_10x5_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_10x5_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_10x6_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_10x6_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_10x10_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_10x10_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_12x10_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_12x10_KHR`
    + `ext.COMPRESSED_RGBA_ASTC_12x12_KHR ext.COMPRESSED_SRGB8_ALPHA8_ASTC_12x12_KHR`
* When using the `EXT_texture_compression_bptc` extension:
    + `ext.COMPRESSED_RGBA_BPTC_UNORM_EXT`
    + `ext.COMPRESSED_SRGB_ALPHA_BPTC_UNORM_EXT`
    + `ext.COMPRESSED_RGB_BPTC_SIGNED_FLOAT_EXT`
    + `ext.COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT_EXT`
* When using the `EXT_texture_compression_rgtc` extension:
    + `ext.COMPRESSED_RED_RGTC1_EXT`
    + `ext.COMPRESSED_SIGNED_RED_RGTC1_EXT`
    + `ext.COMPRESSED_RED_GREEN_RGTC2_EXT`
    + `ext.COMPRESSED_SIGNED_RED_GREEN_RGTC2_EXT`

`width`

A `GLsizei` specifying the width of the texture.

`height`

A `GLsizei` specifying the height of the texture.

`depth`

 A `GLsizei` specifying the depth of the texture/the number of textures
 in a `TEXTURE_2D_ARRAY`.


`border`

A `GLint` specifying the width of the border. Must be 0.

`imageSize`

 A `GLsizei` specifying the number of bytes to read from the buffer
 bound to `gl.PIXEL_UNPACK_BUFFER`.


`offset`

 A `GLintptr` specifying the offset in bytes from which to read from the
 buffer bound to `gl.PIXEL_UNPACK_BUFFER`.


`pixels`

 A `TypedArray` or a `DataView` that will be used as a data store for the
 compressed image data in memory.


### Return value

None (`undefined`).

Examples
--------


```js
const ext =
  gl.getExtension("WEBGL\_compressed\_texture\_s3tc") ||
  gl.getExtension("MOZ\_WEBGL\_compressed\_texture\_s3tc") ||
  gl.getExtension("WEBKIT\_WEBGL\_compressed\_texture\_s3tc");

const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE\_2D, texture);
gl.compressedTexImage2D(
  gl.TEXTURE\_2D,
  0,
  ext.COMPRESSED\_RGBA\_S3TC\_DXT5\_EXT,
  512,
  512,
  0,
  textureData,
);
gl.texParameteri(gl.TEXTURE\_2D, gl.TEXTURE\_MAG\_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE\_2D, gl.TEXTURE\_MIN\_FILTER, gl.LINEAR);
```

Specifications
--------------

| Specification |
| --- |
| WebGL Specification # COMPRESSEDTEXIMAGE2D |
| WebGL 2.0 Specification # 3.7.6 |

Browser compatibility
---------------------

### api.WebGLRenderingContext.compressedTexImage2D

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.WebGL2RenderingContext.compressedTexImage3D

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using WebGL extensions
* `WebGLRenderingContext.compressedTexSubImage2D()`
* `WEBGL_compressed_texture_s3tc`
* `WEBGL_compressed_texture_s3tc_srgb`
* `WEBGL_compressed_texture_etc`
* `WEBGL_compressed_texture_pvrtc`
* `WEBGL_compressed_texture_etc1`
* `WEBGL_compressed_texture_astc`
* `EXT_texture_compression_bptc`
* `EXT_texture_compression_rgtc`