'\" t .\" Title: glTexImage1D .\" 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 "GLTEXIMAGE1D" "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" glTexImage1D \- specify a one\-dimensional texture image .SH "C SPECIFICATION" .HP \w'void\ glTexImage1D('u .BI "void glTexImage1D(GLenum\ " "target" ", GLint\ " "level" ", GLint\ " "internalFormat" ", GLsizei\ " "width" ", GLint\ " "border" ", GLenum\ " "format" ", GLenum\ " "type" ", const\ GLvoid\ *\ " "data" ");" .PP .SH "PARAMETERS" .PP \fItarget\fR .RS 4 Specifies the target texture\&. Must be \fBGL_TEXTURE_1D\fR or \fBGL_PROXY_TEXTURE_1D\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 number of color components in the texture\&. Must be one of the following symbolic constants: \fBGL_COMPRESSED_RED\fR, \fBGL_COMPRESSED_RG\fR, \fBGL_COMPRESSED_RGB\fR, \fBGL_COMPRESSED_RGBA\fR, \fBGL_COMPRESSED_SRGB\fR, \fBGL_COMPRESSED_SRGB_ALPHA\fR, \fBGL_DEPTH_COMPONENT\fR, \fBGL_DEPTH_COMPONENT16\fR, \fBGL_DEPTH_COMPONENT24\fR, \fBGL_DEPTH_COMPONENT32\fR, \fBGL_R3_G3_B2\fR, \fBGL_RED\fR, \fBGL_RG\fR, \fBGL_RGB\fR, \fBGL_RGB4\fR, \fBGL_RGB5\fR, \fBGL_RGB8\fR, \fBGL_RGB10\fR, \fBGL_RGB12\fR, \fBGL_RGB16\fR, \fBGL_RGBA\fR, \fBGL_RGBA2\fR, \fBGL_RGBA4\fR, \fBGL_RGB5_A1\fR, \fBGL_RGBA8\fR, \fBGL_RGB10_A2\fR, \fBGL_RGBA12\fR, \fBGL_RGBA16\fR, \fBGL_SRGB\fR, \fBGL_SRGB8\fR, \fBGL_SRGB_ALPHA\fR, or \fBGL_SRGB8_ALPHA8\fR\&. .RE .PP \fIwidth\fR .RS 4 Specifies the width of the texture image\&. All implementations support texture images that are at least 1024 texels wide\&. The height of the 1D texture image is 1\&. .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 one\-dimensional texturing, call \fBglEnable\fR() and \fBglDisable\fR() with argument \fBGL_TEXTURE_1D\fR\&. .PP Texture images are defined with \fBglTexImage1D\fR\&. The arguments describe the parameters of the texture image, such as width, width of the border, level\-of\-detail number (see \fBglTexParameter\fR()), and the internal resolution and format used to store the image\&. The last three arguments describe how the image is represented in memory\&. .PP If \fItarget\fR is \fBGL_PROXY_TEXTURE_1D\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_1D\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 left end of the texture array\&. Subsequent elements progress left\-to\-right through the remaining texels in the texture array\&. The final element corresponds to the right end of the texture array\&. .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 single red/green double The GL converts it 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 \fBGL_DEPTH_COMPONENT\fR .RS 4 Each element is a single depth value\&. The GL converts it to floating point, multiplies by the signed scale factor \fBGL_DEPTH_SCALE\fR, adds the signed bias \fBGL_DEPTH_BIAS\fR, and clamps 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\fRor \fBGL_SRGB8_ALPHA8\fR, the texture is treated as if the red, green, or blue 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_1D\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 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\&. .PP Image\-based shadowing can be enabled by comparing texture r coordinates to depth texture values to generate a boolean result\&. See \fBglTexParameter\fR() for details on texture comparison\&. .SH "NOTES" .PP \fBglPixelStore\fR() modes affect 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\&. You can then download subtextures to initialize the texture memory\&. The image is undefined if the program tries to apply an uninitialized portion of the texture image to a primitive\&. .PP \fBglTexImage1D\fR specifies the one\-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_1D\fR or \fBGL_PROXY_TEXTURE_1D\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 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 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 cannot be represented as 2 n + 2 ⁡ border for some integer value of \fIn\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 is \fBGL_DEPTH_COMPONENT\fR and \fIinternalFormat\fR is not \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 \fIinternalFormat\fR is \fBGL_DEPTH_COMPONENT\fR, \fBGL_DEPTH_COMPONENT16\fR, \fBGL_DEPTH_COMPONENT24\fR, or \fBGL_DEPTH_COMPONENT32\fR, and \fIformat\fR is not \fBGL_DEPTH_COMPONENT\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(), \fBglCompressedTexSubImage1D\fR(), \fBglCopyTexImage1D\fR(), \fBglCopyTexSubImage1D\fR(), \fBglGetCompressedTexImage\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[]\&.