'\" t .\" Title: glTexImage3D .\" 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 "GLTEXIMAGE3D" "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" glTexImage3D \- specify a three\-dimensional texture image .SH "C SPECIFICATION" .HP \w'void\ glTexImage3D('u .BI "void glTexImage3D(GLenum\ " "target" ", GLint\ " "level" ", GLint\ " "internalFormat" ", GLsizei\ " "width" ", GLsizei\ " "height" ", GLsizei\ " "depth" ", GLint\ " "border" ", GLenum\ " "format" ", GLenum\ " "type" ", const\ GLvoid\ *\ " "data" ");" .PP .SH "PARAMETERS" .PP \fItarget\fR .RS 4 Specifies the target texture\&. Must be one of \fBGL_TEXTURE_3D\fR, \fBGL_PROXY_TEXTURE_3D\fR, \fBGL_TEXTURE_2D_ARRAY\fR or \fBGL_PROXY_TEXTURE_2D_ARRAY\fR\&. .RE .PP \fIlevel\fR .RS 4 Specifies the level\-of\-detail number\&. Level 0 is the base image level\&. Level n is the n th mipmap reduction image\&. .RE .PP \fIinternalFormat\fR .RS 4 Specifies the number of color components in the texture\&. Must be one of the following symbolic constants: \fBGL_RGBA32F\fR, \fBGL_RGBA32I\fR, \fBGL_RGBA32UI\fR, \fBGL_RGBA16\fR, \fBGL_RGBA16F\fR, \fBGL_RGBA16I\fR, \fBGL_RGBA16UI\fR, \fBGL_RGBA8\fR, \fBGL_RGBA8UI\fR, \fBGL_SRGB8_ALPHA8\fR, \fBGL_RGB10_A2\fR, \fBGL_RGBA10_A2UI\fR, \fBGL_R11_G11_B10F\fR, \fBGL_RG32F\fR, \fBGL_RG32I\fR, \fBGL_RG32UI\fR, \fBGL_RG16\fR, \fBGL_RG16F\fR, \fBGL_RGB16I\fR, \fBGL_RGB16UI\fR, \fBGL_RG8\fR, \fBGL_RG8I\fR, \fBGL_RG8UI\fR, \fBGL_R23F\fR, \fBGL_R32I\fR, \fBGL_R32UI\fR, \fBGL_R16F\fR, \fBGL_R16I\fR, \fBGL_R16UI\fR, \fBGL_R8\fR, \fBGL_R8I\fR, \fBGL_R8UI\fR, \fBGL_RGBA16_UNORM\fR, \fBGL_RGBA8_SNORM\fR, \fBGL_RGB32F\fR, \fBGL_RGB32I\fR, \fBGL_RGB32UI\fR, \fBGL_RGB16_SNORM\fR, \fBGL_RGB16F\fR, \fBGL_RGB16I\fR, \fBGL_RGB16UI\fR, \fBGL_RGB16\fR, \fBGL_RGB8_SNORM\fR, \fBGL_RGB8\fR, \fBGL_RGB8I\fR, \fBGL_RGB8UI\fR, \fBGL_SRGB8\fR, \fBGL_RGB9_E5\fR, \fBGL_RG16_SNORM\fR, \fBGL_RG8_SNORM\fR, \fBGL_COMPRESSED_RG_RGTC2\fR, \fBGL_COMPRESSED_SIGNED_RG_RGTC2\fR, \fBGL_R16_SNORM\fR, \fBGL_R8_SNORM\fR, \fBGL_COMPRESSED_RED_RGTC1\fR, \fBGL_COMPRESSED_SIGNED_RED_RGTC1\fR, \fBGL_DEPTH_COMPONENT32F\fR, \fBGL_DEPTH_COMPONENT24\fR, \fBGL_DEPTH_COMPONENT16\fR, \fBGL_DEPTH32F_STENCIL8\fR, \fBGL_DEPTH24_STENCIL8\fR\&. .RE .PP \fIwidth\fR .RS 4 Specifies the width of the texture image\&. All implementations support 3D 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 3D texture images that are at least 256 texels high\&. .RE .PP \fIdepth\fR .RS 4 Specifies the depth of the texture image, or the number of layers in a texture array\&. All implementations support 3D texture images that are at least 256 texels deep, and texture arrays that are at least 256 layers deep\&. .RE .PP \fIborder\fR .RS 4 This value must be 0\&. .RE .PP \fIformat\fR .RS 4 Specifies the format of the pixel data\&. The following symbolic values are accepted: \fBGL_RED\fR, \fBGL_RG\fR, \fBGL_RGB\fR, \fBGL_BGR\fR, \fBGL_RGBA\fR, and \fBGL_BGRA\fR\&. .RE .PP \fItype\fR .RS 4 Specifies the data type of the pixel data\&. The following symbolic values are accepted: \fBGL_UNSIGNED_BYTE\fR, \fBGL_BYTE\fR, \fBGL_UNSIGNED_SHORT\fR, \fBGL_SHORT\fR, \fBGL_UNSIGNED_INT\fR, \fBGL_INT\fR, \fBGL_FLOAT\fR, \fBGL_UNSIGNED_BYTE_3_3_2\fR, \fBGL_UNSIGNED_BYTE_2_3_3_REV\fR, \fBGL_UNSIGNED_SHORT_5_6_5\fR, \fBGL_UNSIGNED_SHORT_5_6_5_REV\fR, \fBGL_UNSIGNED_SHORT_4_4_4_4\fR, \fBGL_UNSIGNED_SHORT_4_4_4_4_REV\fR, \fBGL_UNSIGNED_SHORT_5_5_5_1\fR, \fBGL_UNSIGNED_SHORT_1_5_5_5_REV\fR, \fBGL_UNSIGNED_INT_8_8_8_8\fR, \fBGL_UNSIGNED_INT_8_8_8_8_REV\fR, \fBGL_UNSIGNED_INT_10_10_10_2\fR, and \fBGL_UNSIGNED_INT_2_10_10_10_REV\fR\&. .RE .PP \fIdata\fR .RS 4 Specifies a pointer to the image data in memory\&. .RE .SH "DESCRIPTION" .PP Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled\&. To enable and disable three\-dimensional texturing, call \fBglEnable\fR() and \fBglDisable\fR() with argument \fBGL_TEXTURE_3D\fR\&. .PP To define texture images, call \fBglTexImage3D\fR\&. The arguments describe the parameters of the texture image, such as height, width, depth, width of the border, level\-of\-detail number (see \fBglTexParameter\fR()), and number of color components provided\&. The last three arguments describe how the image is represented in memory\&. .PP If \fItarget\fR is \fBGL_PROXY_TEXTURE_3D\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 If \fItarget\fR is \fBGL_TEXTURE_3D\fR, data is read from \fIdata\fR as a sequence of signed or unsigned bytes, shorts, or longs, or single\-precision floating\-point values, depending on \fItype\fR\&. These values are grouped into sets of one, two, three, or four values, depending on \fIformat\fR, to form elements\&. Each data byte is treated as eight 1\-bit elements, with bit ordering determined by \fBGL_UNPACK_LSB_FIRST\fR (see \fBglPixelStore\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\&. .PP The first element corresponds to the lower left corner of the texture image\&. Subsequent elements progress left\-to\-right through the remaining texels in the lowest row of the texture image, and then in successively higher rows of the texture image\&. The final element corresponds to the upper right corner of the texture image\&. .PP \fIformat\fR determines the composition of each element in \fIdata\fR\&. It can assume one of these symbolic values: .PP \fBGL_RED\fR .RS 4 Each element is a single red component\&. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for green and blue, and 1 for alpha\&. Each component is then multiplied by the signed scale factor \fBGL_c_SCALE\fR, added to the signed bias \fBGL_c_BIAS\fR, and clamped to the range [0,1]\&. .RE .PP \fBGL_RG\fR .RS 4 Each element is a red and green pair\&. The GL converts each to floating point and assembles it into an RGBA element by attaching 0 for blue, and 1 for alpha\&. Each component is then multiplied by the signed scale factor \fBGL_c_SCALE\fR, added to the signed bias \fBGL_c_BIAS\fR, and clamped to the range [0,1]\&. .RE .PP \fBGL_RGB\fR .RS 4 .RE .PP \fBGL_BGR\fR .RS 4 Each element is an RGB triple\&. The GL converts it to floating point and assembles it into an RGBA element by attaching 1 for alpha\&. Each component is then multiplied by the signed scale factor \fBGL_c_SCALE\fR, added to the signed bias \fBGL_c_BIAS\fR, and clamped to the range [0,1]\&. .RE .PP \fBGL_RGBA\fR .RS 4 .RE .PP \fBGL_BGRA\fR .RS 4 Each element contains all four components\&. Each component is multiplied by the signed scale factor \fBGL_c_SCALE\fR, added to the signed bias \fBGL_c_BIAS\fR, and clamped to the range [0,1]\&. .RE .PP If an application wants to store the texture at a certain resolution or in a certain format, it can request the resolution and format with \fIinternalFormat\fR\&. The GL will choose an internal representation that closely approximates that requested by \fIinternalFormat\fR, but it may not match exactly\&. (The representations specified by \fBGL_RED\fR, \fBGL_RG\fR, \fBGL_RGB\fR, and \fBGL_RGBA\fR must match exactly\&.) .PP If the \fIinternalFormat\fR parameter is one of the generic compressed formats, \fBGL_COMPRESSED_RED\fR, \fBGL_COMPRESSED_RG\fR, \fBGL_COMPRESSED_RGB\fR, or \fBGL_COMPRESSED_RGBA\fR, the GL will replace the internal format with the symbolic constant for a specific internal format and compress the texture before storage\&. If no corresponding internal format is available, or the GL can not compress that image for any reason, the internal format is instead replaced with a corresponding base internal format\&. .PP If the \fIinternalFormat\fR parameter is \fBGL_SRGB\fR, \fBGL_SRGB8\fR, \fBGL_SRGB_ALPHA\fR, or \fBGL_SRGB8_ALPHA8\fR, the texture is treated as if the red, green, blue, or luminance components are encoded in the sRGB color space\&. Any alpha component is left unchanged\&. The conversion from the sRGB encoded component c s to a linear component c l is: .PP c l = { c s 12\&.92 if c s ≤ 0\&.04045 ( c s + 0\&.055 1\&.055 ) 2\&.4 if c s > 0\&.04045 .PP Assume c s is the sRGB component in the range [0,1]\&. .PP Use the \fBGL_PROXY_TEXTURE_3D\fR target to try out a resolution and format\&. The implementation will update and recompute its best match for the requested storage resolution and format\&. To then query this state, call \fBglGetTexLevelParameter\fR()\&. If the texture cannot be accommodated, texture state is set to 0\&. .PP A one\-component texture image uses only the red component of the RGBA color extracted from \fIdata\fR\&. A two\-component image uses the R and A values\&. A three\-component image uses the R, G, and B values\&. A four\-component image uses all of the RGBA components\&. .SH "NOTES" .PP The \fBglPixelStore\fR() mode affects texture images\&. .PP \fIdata\fR may be a null pointer\&. In this case texture memory is allocated to accommodate a texture of width \fIwidth\fR, height \fIheight\fR, and depth \fIdepth\fR\&. You can then download subtextures to initialize this texture memory\&. The image is undefined if the user tries to apply an uninitialized portion of the texture image to a primitive\&. .PP \fBglTexImage3D\fR specifies the three\-dimensional texture for the current texture unit, specified with \fBglActiveTexture\fR()\&. .SH "ERRORS" .PP \fBGL_INVALID_ENUM\fR is generated if \fItarget\fR is not \fBGL_TEXTURE_3D\fR or \fBGL_PROXY_TEXTURE_3D\fR\&. .PP \fBGL_INVALID_ENUM\fR is generated if \fIformat\fR is not an accepted format constant\&. Format constants other than \fBGL_STENCIL_INDEX\fR and \fBGL_DEPTH_COMPONENT\fR are accepted\&. .PP \fBGL_INVALID_ENUM\fR is generated if \fItype\fR is not a type constant\&. .PP \fBGL_INVALID_VALUE\fR is generated if \fIlevel\fR is less than 0\&. .PP \fBGL_INVALID_VALUE\fR may be generated if \fIlevel\fR is greater than log 2 ⁡ max, where \fImax\fR is the returned value of \fBGL_MAX_TEXTURE_SIZE\fR\&. .PP \fBGL_INVALID_VALUE\fR is generated if \fIinternalFormat\fR is not one of the accepted resolution and format symbolic constants\&. .PP \fBGL_INVALID_VALUE\fR is generated if \fIwidth\fR, \fIheight\fR, or \fIdepth\fR is less than 0 or greater than \fBGL_MAX_TEXTURE_SIZE\fR\&. .PP \fBGL_INVALID_VALUE\fR is generated if non\-power\-of\-two textures are not supported and the \fIwidth\fR, \fIheight\fR, or \fIdepth\fR cannot be represented as 2 k + 2 ⁡ border for some integer value of \fIk\fR\&. .PP \fBGL_INVALID_VALUE\fR is generated if \fIborder\fR is not 0 or 1\&. .PP \fBGL_INVALID_OPERATION\fR is generated if \fItype\fR is one of \fBGL_UNSIGNED_BYTE_3_3_2\fR, \fBGL_UNSIGNED_BYTE_2_3_3_REV\fR, \fBGL_UNSIGNED_SHORT_5_6_5\fR, or \fBGL_UNSIGNED_SHORT_5_6_5_REV\fR and \fIformat\fR is not \fBGL_RGB\fR\&. .PP \fBGL_INVALID_OPERATION\fR is generated if \fItype\fR is one of \fBGL_UNSIGNED_SHORT_4_4_4_4\fR, \fBGL_UNSIGNED_SHORT_4_4_4_4_REV\fR, \fBGL_UNSIGNED_SHORT_5_5_5_1\fR, \fBGL_UNSIGNED_SHORT_1_5_5_5_REV\fR, \fBGL_UNSIGNED_INT_8_8_8_8\fR, \fBGL_UNSIGNED_INT_8_8_8_8_REV\fR, \fBGL_UNSIGNED_INT_10_10_10_2\fR, or \fBGL_UNSIGNED_INT_2_10_10_10_REV\fR and \fIformat\fR is neither \fBGL_RGBA\fR nor \fBGL_BGRA\fR\&. .PP \fBGL_INVALID_OPERATION\fR is generated if \fIformat\fR or \fIinternalFormat\fR is \fBGL_DEPTH_COMPONENT\fR, \fBGL_DEPTH_COMPONENT16\fR, \fBGL_DEPTH_COMPONENT24\fR, or \fBGL_DEPTH_COMPONENT32\fR\&. .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 \fBGL_INVALID_OPERATION\fR is generated if a non\-zero buffer object name is bound to the \fBGL_PIXEL_UNPACK_BUFFER\fR target and \fIdata\fR is not evenly divisible into the number of bytes needed to store in memory a datum indicated by \fItype\fR\&. .SH "ASSOCIATED GETS" .PP \fBglGetTexImage\fR() .PP \fBglGet\fR() with argument \fBGL_PIXEL_UNPACK_BUFFER_BINDING\fR .SH "SEE ALSO" .PP \fBglActiveTexture\fR(), \fBglCompressedTexImage1D\fR(), \fBglCompressedTexImage2D\fR(), \fBglCompressedTexImage3D\fR(), \fBglCompressedTexSubImage1D\fR(), \fBglCompressedTexSubImage2D\fR(), \fBglCompressedTexSubImage3D\fR(), \fBglCopyTexImage1D\fR(), \fBglCopyTexImage2D\fR(), \fBglCopyTexSubImage1D\fR(), \fBglCopyTexSubImage2D\fR(), \fBglCopyTexSubImage3D\fR(), \fBglGetCompressedTexImage\fR(), \fBglPixelStore\fR(), \fBglTexImage1D\fR(), \fBglTexImage2D\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[]\&.