2003-2004 Silicon Graphics, Inc.
glCompressedTexImage2D 3G
glCompressedTexImage2D specify a two-dimensional compressed texture image

## C Specification

void `glCompressedTexImage2D` GLenum target GLint level GLenum internalformat GLsizei width GLsizei height GLint border GLsizei imageSize const GLvoid * data

## Parameters

target

  Specifies the target texture. Must be `GL_TEXTURE_2D`.

level

  Specifies the level-of-detail number. For paletted formats, where all mipmap levels are loaded at once, this parameter is overloaded to represent the negative of the greatest mipmap level included in data.

internalformat

  Specifies the color components in the texture. The following symbolic constants are accepted: `GL_PALETTE4_RGB8_OES`, `GL_PALETTE4_RGBA8_OES`, `GL_PALETTE4_R5_G6_B5_OES`, `GL_PALETTE4_RGBA4_OES`, `GL_PALETTE4_RGB5_A1_OES`, `GL_PALETTE8_RGB8_OES`, `GL_PALETTE8_RGBA8_OES`, `GL_PALETTE8_R5_G6_B5_OES`, `GL_PALETTE8_RGBA4_OES`, and `GL_PALETTE8_RGB5_A1_OES`.

width

  Specifies the width of the texture image. Must be 2 n for some integer n. All implementations support texture images that are at least 64 texels wide.

height

  Specifies the height of the texture image. Must be 2 m for some integer m. All implementations support texture images that are at least 64 texels high.

border

  Specifies the width of the border. Must be 0.

imageSize

  Specifies the size of the compressed image data in bytes.

data

  Specifies a pointer to the compressed image data in memory.

## Description

`glCompressedTexImage2D` defines a two-dimensional texture image or cube-map texture image using compressed image data from client memory. The texture image is decoded according to the definition of the internalformat. In addition to the paletted formats described below, OpenGL ES provides a mechanism to obtain symbolic constants for other formats provided by extensions. The number of compressed texture formats supported can be obtained by querying the value of `GL_NUM_COMPRESSED_TEXTURE_FORMATS`. The list of specific compressed texture formats supported can be obtained by querying the value of `GL_COMPRESSED_TEXTURE_FORMATS`.

The required compressed formats are paletted textures. The layout of the compressed image is a palette followed by multiple mip-levels of texture indices used for lookup into the palette. The palette format can be one of `R5_G6_B5`, `RGBA4`, `RGB5_A1`, `RGB8`, or `RGBA8`. The texture indices can have a resolution of 4 or 8 bits. As a result, the number of palette entries is either 16 or 256. If level is 0, only one mip-level of texture indices is described in data. Otherwise, the negative value of level specifies up to which mip-level the texture indices are described. A possibly remaining pad nibble for the lowest resolution mip-level is ignored.

## Notes

glPixelStorei has no effect on compressed texture images.

`glCompressedTexImage2D` specifies the two-dimensional texture for the currently bound texture, specified with glBindTexture, and the current texture unit, specified with glActiveTexture.

## Errors

`GL_INVALID_ENUM` is generated if target is not `GL_TEXTURE_2D`.

`GL_INVALID_VALUE` may be generated if internalformat is not one of the paletted formats and level is greater than 0 or the absolute value of level is greater than log 2 max , where max is the returned value of `GL_MAX_TEXTURE_SIZE`.

`GL_INVALID_VALUE` may be generated if internalformat is not one of the paletted formats and level is less than 0 or greater than log 2 max , where max is the returned value of `GL_MAX_TEXTURE_SIZE`.

`GL_INVALID_ENUM` is generated if internalformat is not one of the accepted symbolic constants.

`GL_INVALID_VALUE` is generated if width or height is less than 0 or greater than `GL_MAX_TEXTURE_SIZE`, or if either cannot be represented as 2 k for some integer k.

`GL_INVALID_VALUE` is generated if border is not 0.

`GL_INVALID_VALUE` is generated if imageSize is not consistent with format, dimensions, and contents of the compressed image.

## Associated Gets

glGet with arguments `GL_NUM_COMPRESSED_TEXTURE_FORMATS` and `GL_COMPRESSED_TEXTURE_FORMATS`

glGet with argument `GL_MAX_TEXTURE_SIZE`

## See Also

glActiveTexture, glBindTexture, glCompressedTexSubImage2D, glCopyTexImage2D, glCopyTexSubImage2D, glPixelStorei, glTexEnv, glTexImage2D, glTexParameter

## Copyright

Copyright 2003-2004 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.