'\" e
'\"! eqn | mmdoc
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 24 September 1999
.ds Re Release 1.2.1
.ds Dp Jan 14 18:30
.ds Dm 01 copytexim
.ds Xs 15515 7 copyteximage2d.gl
.TH GLCOPYTEXIMAGE2D 3G
.SH NAME
.B "glCopyTexImage2D
\- copy pixels into a 2D texture image

.SH C SPECIFICATION
void \f3glCopyTexImage2D\fP(
GLenum \fItarget\fP,
.nf
.ta \w'\f3void \fPglCopyTexImage2D( 'u
	GLint \fIlevel\fP,
	GLenum \fIinternalformat\fP,
	GLint \fIx\fP,
	GLint \fIy\fP,
	GLsizei \fIwidth\fP,
	GLsizei \fIheight\fP,
	GLint \fIborder\fP )
.fi

.EQ
delim $$
.EN
.SH PARAMETERS
.TP \w'\fIinternalformat\fP\ \ 'u 
\f2target\fP
Specifies the target texture.
Must be \%\f3GL_TEXTURE_2D\fP.
.TP
\f2level\fP
Specifies the level-of-detail number.
Level 0 is the base image level.
Level \f2n\fP is the \f2n\fPth mipmap reduction image.
.TP
\f2internalformat\fP
Specifies the internal  of the texture.
Must be one of the following symbolic constants:
\%\f3GL_ALPHA\fP,
\%\f3GL_ALPHA4\fP,
\%\f3GL_ALPHA8\fP,
\%\f3GL_ALPHA12\fP,
\%\f3GL_ALPHA16\fP,
\%\f3GL_LUMINANCE\fP,
\%\f3GL_LUMINANCE4\fP,
\%\f3GL_LUMINANCE8\fP,
\%\f3GL_LUMINANCE12\fP,
\%\f3GL_LUMINANCE16\fP,
\%\f3GL_LUMINANCE_ALPHA\fP,
\%\f3GL_LUMINANCE4_ALPHA4\fP,
\%\f3GL_LUMINANCE6_ALPHA2\fP,
\%\f3GL_LUMINANCE8_ALPHA8\fP,
\%\f3GL_LUMINANCE12_ALPHA4\fP,
\%\f3GL_LUMINANCE12_ALPHA12\fP,
\%\f3GL_LUMINANCE16_ALPHA16\fP,
\%\f3GL_INTENSITY\fP,
\%\f3GL_INTENSITY4\fP,
\%\f3GL_INTENSITY8\fP,
\%\f3GL_INTENSITY12\fP,
\%\f3GL_INTENSITY16\fP,
\%\f3GL_RGB\fP,
\%\f3GL_R3_G3_B2\fP,
\%\f3GL_RGB4\fP,
\%\f3GL_RGB5\fP,
\%\f3GL_RGB8\fP,
\%\f3GL_RGB10\fP,
\%\f3GL_RGB12\fP,
\%\f3GL_RGB16\fP,
\%\f3GL_RGBA\fP,
\%\f3GL_RGBA2\fP,
\%\f3GL_RGBA4\fP,
\%\f3GL_RGB5_A1\fP,
\%\f3GL_RGBA8\fP,
\%\f3GL_RGB10_A2\fP,
\%\f3GL_RGBA12\fP, or
\%\f3GL_RGBA16\fP.
.TP
\f2x\fP, \f2y\fP
Specify the window coordinates of the lower left corner
of the rectangular region of pixels to be copied.
.TP
\f2width\fP
Specifies the width of the texture image.
Must be 0 or $2 sup n ~+~ 2*$\f2border\fP for some integer $n$.
.TP
\f2height\fP
Specifies the height of the texture image.
Must be 0 or $2 sup m ~+~ 2*$\f2border\fP for some integer $m$.
.TP
\f2border\fP
Specifies the width of the border.
Must be either 0 or 1.
.SH DESCRIPTION
\%\f3glCopyTexImage2D\fP defines a two-dimensional texture image with pixels from the current
\%\f3GL_READ_BUFFER\fP.
.P
The screen-aligned pixel rectangle with lower left corner at (\f2x\fP,
\f2y\fP) and with a width of \f2width\fP$~+~2~*~$\f2border\fP and a height of
\f2height\fP$~+~2~*~$\f2border\fP 
defines the texture array
at the mipmap level specified by \f2level\fP.
\f2internalformat\fP specifies the internal  of the texture array.
.P
The pixels in the rectangle are processed exactly as if
\%\f3glCopyPixels\fP had been called, but the process stops just before
final conversion.
At this point all pixel component values are clamped to the range $[0,1]$
and then converted to the texture's internal  for storage in the texel
array.
.P
Pixel ordering is such that lower $x$ and $y$ screen coordinates correspond to 
lower $s$ and $t$ texture coordinates.
.P
If any of the pixels within the specified rectangle of the current
\%\f3GL_READ_BUFFER\fP are outside the window associated with the current
rendering context, then the values obtained for those pixels are undefined.
.P
.SH NOTES
\%\f3glCopyTexImage2D\fP is available only if the GL version is 1.1 or greater.
.P
Texturing has no effect in color index mode.
.P
1, 2, 3, and 4 are not accepted values for \f2internalformat\fP.
.P 
An image with height or width of 0 indicates a NULL texture. 
.P
When the \%\f3GL_ARB_imaging\fP extension is supported, the RGBA components
read from the framebuffer may be processed by the imaging pipeline.  See
\%\f3glTexImage1D\fP for specific details.
.SH ERRORS
\%\f3GL_INVALID_ENUM\fP is generated if \f2target\fP is not \%\f3GL_TEXTURE_2D\fP.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2level\fP is less than 0.
.P 
\%\f3GL_INVALID_VALUE\fP may be generated if \f2level\fP is greater
than $log sub 2 max$,
where $max$ is the returned value of \%\f3GL_MAX_TEXTURE_SIZE\fP.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2width\fP or \f2height\fP is less than 0,
greater than $2~+~$\%\f3GL_MAX_TEXTURE_SIZE\fP, or if \f2width\fP or \f2height\fP cannot be
represented as $2 sup k ~+~ 2~*~$\f2border\fP for some integer
$k$.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2border\fP is not 0 or 1.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2internalformat\fP is not one of the
allowable values.
.P
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glCopyTexImage2D\fP is executed
between the execution of \%\f3glBegin\fP and the corresponding
execution of \%\f3glEnd\fP.
.SH ASSOCIATED GETS
\%\f3glGetTexImage\fP
.br
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_2D\fP
.SH SEE ALSO
\%\f3glCopyPixels(3G)\fP,
\%\f3glCopyTexImage1D(3G)\fP,
\%\f3glCopyTexSubImage1D(3G)\fP,
\%\f3glCopyTexSubImage2D(3G)\fP,
\%\f3glPixelStore(3G)\fP,
\%\f3glPixelTransfer(3G)\fP,
\%\f3glTexEnv(3G)\fP,
\%\f3glTexGen(3G)\fP,
\%\f3glTexImage1D(3G)\fP,
\%\f3glTexImage2D(3G)\fP,
\%\f3glTexSubImage1D(3G)\fP,
\%\f3glTexSubImage2D(3G)\fP,
.br
\%\f3glTexParameter(3G)\fP