'\" t .\" Title: glCompressedTexImage2D .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 03/08/2011 .\" Manual: OpenGL 3.3 .\" Source: OpenGL 3.3 .\" Language: English .\" .TH "GLCOMPRESSEDTEXIMAGE" "3G" "03/08/2011" "OpenGL 3.3" "OpenGL 3\&.3" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" glCompressedTexImage2D \- specify a two\-dimensional texture image in a compressed format .SH "C SPECIFICATION" .HP \w'void\ glCompressedTexImage2D('u .BI "void glCompressedTexImage2D(GLenum\ " "target" ", GLint\ " "level" ", GLenum\ " "internalformat" ", GLsizei\ " "width" ", GLsizei\ " "height" ", GLint\ " "border" ", GLsizei\ " "imageSize" ", const\ GLvoid\ *\ " "data" ");" .SH "PARAMETERS" .PP \fItarget\fR .RS 4 Specifies the target texture\&. Must be \fBGL_TEXTURE_2D\fR, \fBGL_PROXY_TEXTURE_2D\fR, \fBGL_TEXTURE_1D_ARRAY\fR, \fBGL_PROXY_TEXTURE_1D_ARRAY\fR, \fBGL_TEXTURE_CUBE_MAP_POSITIVE_X\fR, \fBGL_TEXTURE_CUBE_MAP_NEGATIVE_X\fR, \fBGL_TEXTURE_CUBE_MAP_POSITIVE_Y\fR, \fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Y\fR, \fBGL_TEXTURE_CUBE_MAP_POSITIVE_Z\fR, \fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Z\fR, or \fBGL_PROXY_TEXTURE_CUBE_MAP\fR\&. .RE .PP \fIlevel\fR .RS 4 Specifies the level\-of\-detail number\&. Level 0 is the base image level\&. Level \fIn\fR is the \fIn\fRth mipmap reduction image\&. .RE .PP \fIinternalformat\fR .RS 4 Specifies the format of the compressed image data stored at address \fIdata\fR\&. .RE .PP \fIwidth\fR .RS 4 Specifies the width of the texture image\&. All implementations support 2D texture images that are at least 64 texels wide and cube\-mapped texture images that are at least 16 texels wide\&. .RE .PP \fIheight\fR .RS 4 Specifies the height of the texture image\&. All implementations support 2D texture images that are at least 64 texels high and cube\-mapped texture images that are at least 16 texels high\&. .RE .PP \fIborder\fR .RS 4 This value must be 0\&. .RE .PP \fIimageSize\fR .RS 4 Specifies the number of unsigned bytes of image data starting at the address specified by \fIdata\fR\&. .RE .PP \fIdata\fR .RS 4 Specifies a pointer to the compressed image data in memory\&. .RE .SH "DESCRIPTION" .PP Texturing allows elements of an image array to be read by shaders\&. .PP \fBglCompressedTexImage2D\fR loads a previously defined, and retrieved, compressed two\-dimensional texture image if \fItarget\fR is \fBGL_TEXTURE_2D\fR, or one of the cube map faces such as \fBGL_TEXTURE_CUBE_MAP_POSITIVE_X\fR\&. (see \fBglTexImage2D\fR())\&. .PP If \fItarget\fR is \fBGL_TEXTURE_1D_ARRAY\fR, \fIdata\fR is treated as an array of compressed 1D textures\&. .PP If \fItarget\fR is \fBGL_PROXY_TEXTURE_2D\fR, \fBGL_PROXY_TEXTURE_1D_ARRAY\fR or \fBGL_PROXY_CUBE_MAP\fR, no data is read from \fIdata\fR, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation\*(Aqs capabilities\&. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see \fBglGetError\fR())\&. To query for an entire mipmap array, use an image array level greater than or equal to 1\&. .PP \fIinternalformat\fR must be a known compressed image format (such as \fBGL_RGTC\fR) or an extension\-specified compressed\-texture format\&. When a texture is loaded with \fBglTexImage2D\fR() using a generic compressed texture format (e\&.g\&., \fBGL_COMPRESSED_RGB\fR), the GL selects from one of its extensions supporting compressed textures\&. In order to load the compressed texture image using \fBglCompressedTexImage2D\fR, query the compressed texture image\*(Aqs size and format using \fBglGetTexLevelParameter\fR()\&. .PP If a non\-zero named buffer object is bound to the \fBGL_PIXEL_UNPACK_BUFFER\fR target (see \fBglBindBuffer\fR()) while a texture image is specified, \fIdata\fR is treated as a byte offset into the buffer object\*(Aqs data store\&. .SH "ERRORS" .PP \fBGL_INVALID_ENUM\fR is generated if \fIinternalformat\fR is not one of the generic compressed internal formats: \fBGL_COMPRESSED_RED\fR, \fBGL_COMPRESSED_RG\fR, \fBGL_COMPRESSED_RGB\fR, \fBGL_COMPRESSED_RGBA\fR\&. \fBGL_COMPRESSED_SRGB\fR, or \fBGL_COMPRESSED_SRGB_ALPHA\fR\&. .PP \fBGL_INVALID_VALUE\fR is generated if \fIimageSize\fR is not consistent with the format, dimensions, and contents of the specified compressed image data\&. .PP \fBGL_INVALID_VALUE\fR is generated if \fIborder\fR is not 0\&. .PP \fBGL_INVALID_OPERATION\fR is generated if parameter combinations are not supported by the specific compressed internal format as specified in the specific texture compression extension\&. .PP \fBGL_INVALID_OPERATION\fR is generated if a non\-zero buffer object name is bound to the \fBGL_PIXEL_UNPACK_BUFFER\fR target and the buffer object\*(Aqs data store is currently mapped\&. .PP \fBGL_INVALID_OPERATION\fR is generated if a non\-zero buffer object name is bound to the \fBGL_PIXEL_UNPACK_BUFFER\fR target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size\&. .PP Undefined results, including abnormal program termination, are generated if \fIdata\fR is not encoded in a manner consistent with the extension specification defining the internal compression format\&. .SH "ASSOCIATED GETS" .PP \fBglGetCompressedTexImage\fR() .PP \fBglGet\fR() with argument \fBGL_TEXTURE_COMPRESSED\fR .PP \fBglGet\fR() with argument \fBGL_PIXEL_UNPACK_BUFFER_BINDING\fR .PP \fBglGetTexLevelParameter\fR() with arguments \fBGL_TEXTURE_INTERNAL_FORMAT\fR and \fBGL_TEXTURE_COMPRESSED_IMAGE_SIZE\fR .SH "SEE ALSO" .PP \fBglActiveTexture\fR(), \fBglCompressedTexImage1D\fR(), \fBglCompressedTexImage3D\fR(), \fBglCompressedTexSubImage1D\fR(), \fBglCompressedTexSubImage2D\fR(), \fBglCompressedTexSubImage3D\fR(), \fBglCopyTexImage1D\fR(), \fBglCopyTexSubImage1D\fR(), \fBglCopyTexSubImage2D\fR(), \fBglCopyTexSubImage3D\fR(), \fBglPixelStore\fR(), \fBglTexImage2D\fR(), \fBglTexImage3D\fR(), \fBglTexSubImage1D\fR(), \fBglTexSubImage2D\fR(), \fBglTexSubImage3D\fR(), \fBglTexParameter\fR() .SH "COPYRIGHT" .PP Copyright \(co 1991\-2006 Silicon Graphics, Inc\&. This document is licensed under the SGI Free Software B License\&. For details, see \m[blue]\fBhttp://oss\&.sgi\&.com/projects/FreeB/\fR\m[]\&.