GLCOMPRESSEDTEXIMAGE3D(3gl)GLCOMPRESSEDTEXIMAGE3D(3gl)NAME
glCompressedTexImage3D - specify a three-dimensional compressed texture
image
C SPECIFICATION
void glCompressedTexImage3D( GLenum target,
GLint level,
GLint internalformat,
GLsizei width,
GLsizei height,
GLsizei depth,
GLint border,
GLsizei imagesize,
const GLvoid *data )
PARAMETERS
target Specifies the target texture. Must be GL_TEXTURE_3D or
GL_PROXY_TEXTURE_3D.
level Specifies the level-of-detail number. Level 0 is the
base image level. Level n is the nth mipmap reduction
image.
internalformat Specifies the specific compressed texture image format.
width Specifies the width of the texture image. Must be
2^n+2(border) 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+2(border) for some integer m. All implementations
support texture images that are at least 64 texels
high.
depth Specifies the depth of the texture image. Must be
2^l+2(border) for some integer l.
border Specifies the width of the border. Must be either 0 or
1.
imagesize Specifies the size (in bytes) of the compressed image
data.
data Specifies a pointer to the compressed image data in
memory.
DESCRIPTION
glCompressedTexImage3D defines a three-dimensional texture image, with
incoming data stored in a specific compressed image format. The tar‐
get, level, internalformat, width, height, depth, border parameters
have the same meaning as in glTexImage3D. data points to compressed
image data stored in the compressed image format corresponding to
internalformat.
The GL provides no specific compressed internal formats but does pro‐
vide a mechanism to obtain the enums for such formats provided by
extensions. The number of specific compressed internal format symbolic
constants supported by the renderer can be obtained by querying the
value of GL_NUM_COMPRESSED_TEXTURE_FORMATS using glGet. The set of spe‐
cific compressed internal format symbolic constants supported by the
renderer can be obtained by querying the value of GL_COMPRESSED_TEX‐
TURE_FORMATS using glGet. Since the GL provides no specific image for‐
mats, using any of the six generic compressed internal formats, GL_COM‐
PRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA,
GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, as
internalformat will result in a GL_INVALID_ENUM error.
For the specific compressed internal formats, the compressed image will
be decoded according to the specification defining the internalformat
token. Compressed texture images are treated as an array of imagesize
ubytes beginning at address data. All pixel storage and pixel transfer
modes are ignored when decoding a compressed texture image. If the
imagesize parameter is not consistent with the format, dimensions, and
contents of the compressed image, a GL_INVALID_VALUE error results. If
the compressed image is not encoded according to the defined image for‐
mat, the results of the call are undefined.
Specific compressed internal formats may impose format-specific
restrictions on the use of the compressed image specification calls or
parameters. For example, the compressed image format might be supported
only for 2D textures or may not allow non-zero border values. Any such
restrictions will be documented in the specification defining the com‐
pressed internal format; violating these restrictions will result in a
GL_INVALID_OPERATION error.
Any restrictions imposed by specific compressed internal formats will
be invariant, meaning that if the GL accepts and stores a texture image
in compressed form, providing the same image to glCompressedTexImage3D
will not result in a GL_INVALID_OPERATION error if the following
restrictions are satisfied:
data points to a compressed texture image returned by
glGetCompressedTexImage.
target, level, and internalformat match the target,
level and format parameters provided to the glGetCompressedTexImage
call returning data.
width, height, depth, border, internalformat,
and imagesize match the values of GL_TEXTURE_WIDTH, GL_TEX‐
TURE_HEIGHT, GL_TEXTURE_DEPTH, GL_TEXTURE_BORDER, GL_TEXTURE_INTER‐
NAL_FORMAT, and GL_TEXTURE_COMPRESSED_IMAGE_SIZE for image level
level in effect at the time of the glGetCompressedTexImage call
returning data.
This guarantee applies not just to images returned by glGetCompressed‐
TexImage, but also to any other properly encoded compressed texture
image of the same size and format.
NOTES
Texturing has no effect in color index mode.
ERRORS
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_3D or
GL_PROXY_TEXTURE_3D.
GL_INVALID_VALUE is generated if level is less than 0.
GL_INVALID_VALUE may be generated if level is greater than log2max,
where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_ENUM is generated if internalformat is any of the six
generic compressed internal formats: GL_COMPRESSED_ALPHA, GL_COM‐
PRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTEN‐
SITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA.
GL_INVALID_VALUE is generated if width, height, or depth is less than
zero or greater than GL_MAX_3D_TEXTURE_SIZE, or if width, height or
depth cannot be represented as 2^k+2(border) for some integer k.
GL_INVALID_VALUE is generated if border is not 0 or 1.
GL_INVALID_OPERATION is generated if glCompressedTexImage3D is executed
between the execution of glBegin and the corresponding execution of
glEnd.
ASSOCIATED GETS
glGetCompressedTexImage, glGet with argument NUM_COMPRESSED_TEX‐
TURE_FORMATS, COMPRESSED_TEXTURE_FORMATS, glGetTexLevelParameter with
argument TEXTURE_COMPRESSED_IMAGE_SIZE, TEXTURE_COMPRESSED, glIsEnabled
with argument GL_TEXTURE_3D.
SEE ALSO
glTexImage3D
25 Sep 02 GLCOMPRESSEDTEXIMAGE3D(3gl)
